Performance & Tooling Modernization: oxlint, Native Testing, and Documentation Overhaul (#402)

* Add CLAUDE.md and AGENTS.md, replace eslint with oxfmt/oxlint

* Remove .cursor directory

* Update AGENTS.md with project info, remove c8 dependency

* Remove mocha and c8 dependencies, simplify test script

* Update oxfmt and oxlint versions

* Use Node's native test runner

* Replace new Array() with Array.from() to fix lint warnings

* Audit fixes: has() TTL check, evict() null guard, lazy default params, setWithEvicted cleanup

* Rewrite README.md for new and experienced developers

* Add docs/API.md with complete API reference

* Update CODE_STYLE_GUIDE.md with actual coding conventions

* Update TECHNICAL_DOCUMENTATION.md to reflect actual implementation

* Revert TECHNICAL_DOCUMENTATION.md changes

* Fix TECHNICAL_DOCUMENTATION.md to accurately reflect implementation

* Fix Mathematical Foundation section in TECHNICAL_DOCUMENTATION.md

- Add removeFromList definition with all 4 prev/next cases
- Expand moveToEnd formula and document 'only node' edge case
- Fix TTL validity invariant to handle expiry=0 when ttl=0

* Fix memory leak, stale data, and improve performance

- Clear prev/next pointers in delete() and evict() to prevent memory leaks
- Fix entries() and values() to not pollute LRU order (access items directly instead of calling get())
- Fix entries() and values() returning stale data with TTL (direct item access instead of get() which can delete expired items)
- Fix expiresAt() to return expiry for expired-but-not-yet-deleted items
- Optimize setWithEvicted() to avoid redundant has()+set() calls
- Remove dead code in moveToEnd() (unreachable edge case)
- Remove obsolete moveToEnd edge case test

* Update AGENTS.md with common issues and implementation notes

* Remove dead code in moveToEnd()

* Update lint script to check formatting

* Replace fmt script with fix script

* Apply formatting fixes

* Add coverage script and rename test file

* Add tests for 100% line coverage

* Add test coverage info to README

* Remove unused eslint config

* Fix Mathematical Foundation section to match implementation

* Update TypeScript definitions to match implementation

* Rebuild distribution files

* fix: rename cache variables in factory function example to avoid redeclaration

* fix: correct values() example comment to reflect input key order

* feat: add oxlint.json configuration

* feat: add .oxfmtrc.json configuration

* feat: update pre-commit hook to run fix, coverage, and stage all changes

* build: update dist files

* fix: clarify entries() and values() ordering in JSDoc

* build: update dist files

* docs: add development principles (DRY, YAGNI, SOLID, OWASP)

* refactor: extract unlink() to eliminate linked list duplication

* build: update dist files

* refactor: remove bypass parameter from set() to simplify API

* refactor: simplify set() and setWithEvicted() API by removing resetTtl parameter

* build: update dist files

* docs: sort methods and properties alphabetically in README

* docs: add badges, TypeScript example, comparison, and contributing guide

* docs: update copyright year to 2026

* docs: fix build badge URL to point to ci.yml

* docs: restore coverage badge

* docs: update package.json description to match README tagline

* docs: optimize package.json keywords for discoverability

* chore: update files array to explicitly list lru.d.ts

* docs: add contributing guide

* docs: update AGENTS.md with correct npm scripts

* docs: update AGENTS.md development workflow section

* docs: rename ESLint Configuration to Lint Configuration

* types: update set() and setWithEvicted() signatures to remove unused parameters

* docs: fix TypeScript signatures in TECHNICAL_DOCUMENTATION.md to match types/lru.d.ts

* docs: fix TTL reset invariant and expiry formula in technical documentation

- Add setWithEvicted() to resetTtl description in Core Components
- Update create() formula to show conditional TTL handling (ttl > 0 ? t_now + ttl : 0)
- Fix TTL Reset Invariant to remove incorrect bypass parameter reference

* perf: remove bypass parameter from evict() to avoid V8 deoptimization

- Simplified evict() signature by removing unused bypass parameter
- All internal callers already guarantee size > 0 before calling evict()
- Reduced code complexity and eliminated unnecessary conditional branch
- Updated TypeScript definitions and documentation

BREAKING CHANGE: evict() no longer accepts bypass parameter

* docs: fix resetTtl description and setWithEvicted return type

- Correct resetTtl description: resets TTL on set() updates, not get()
- Fix setWithEvicted return type: {key, value, expiry} only (no prev/next)

All 54 tests passing.

* build: update distribution files

* refactor: make unlink() private and update Node.js version requirement

- Convert unlink() to private field (#unlink) for true encapsulation
- Update engines.node from >=12 to >=14 to support private class fields
- All 54 tests passing

* refactor: simplify JSDoc by removing @example, @see, @SInCE, @method, @memberof

- Removed @example, @see, and @SInCE tags from all method docblocks
- Removed @method and @memberof tags (redundant for class methods)
- Kept @param, @returns, @throws, @Private, and @constructor where needed
- Updated distribution files via build
- All 54 tests passing

* test: update tests to match current API and add edge case coverage

- Remove outdated tests using removed resetTtl parameter from set()/setWithEvicted()
- Add tests for garbage collection (prev/next pointer cleanup)
- Add tests for first/last pointer consistency after deletions
- Add tests for different value types (functions, objects, arrays, null, undefined)
- Add tests for unlimited cache edge cases
- Add tests for array methods with non-existent keys
- Add test verifying get() does NOT reset TTL
- Remove object key test (not supported - keys coerced to strings)

Total: 69 tests, 14 suites, all passing

* docs: update Node.js version requirement to 14+ and fix test runner reference

- Update README.md to require Node.js ≥14 (for private class fields)
- Update docs/TECHNICAL_DOCUMENTATION.md to reference Node.js test runner instead of mocha

Author: avoidwork

.cursor/rules/javascript.mdc

@@ -1,2 +1,2 @@
 
-npm test
+npm run fix && npm run coverage && git add -A

.husky/pre-commit

@@ -0,0 +1,5 @@
+{
+	"$schema": "./node_modules/oxfmt/configuration_schema.json",
+	"ignorePatterns": [],
+	"useTabs": true
+}

.oxfmtrc.json

@@ -0,0 +1,84 @@
+# AGENTS.md
+
+## Project Overview
+
+`tiny-lru` is a high-performance, lightweight LRU (Least Recently Used) cache library for JavaScript with O(1) operations and optional TTL support.
+
+## Setup Commands
+
+```bash
+npm install          # Install dependencies
+npm run build        # Lint and build (runs lint then rollup)
+npm run rollup       # Build with rollup
+npm run test         # Run lint and tests
+npm run coverage     # Run tests with coverage reporting
+npm run fix          # Fix linting and formatting issues
+npm run lint         # Lint code with oxlint
+```
+
+## Development Workflow
+
+Source code is in `src/`.
+
+- **lint**: Check and fix linting issues with oxlint
+- **fix**: Fix linting and formatting issues
+- **build**: Lint + rollup build
+- **coverage**: Run test suite with coverage reporting
+
+## Project Structure
+
+```
+├── src/lru.js          # Main LRU cache implementation
+├── tests/              # Test files
+├── benchmarks/          # Performance benchmarks
+├── dist/               # Built distribution files
+├── types/              # TypeScript definitions
+├── docs/               # Documentation
+├── rollup.config.js    # Build configuration
+└── package.json       # Project configuration
+```
+
+## Code Style
+
+- Indentation: Tabs
+- Quotes: Double quotes
+- Semicolons: Required
+- Array constructor: Avoid `new Array()` (oxlint will warn)
+
+## Development Principles
+
+- **DRY (Don't Repeat Yourself)**: Extract common logic into reusable functions; avoid duplication
+- **YAGNI (You Ain't Gonna Need It)**: Implement only what's needed; avoid over-engineering
+- **SOLID**: Follow single responsibility, open/closed, and interface segregation principles
+- **OWASP**: Prioritize security; avoid unsafe operations, validate inputs, prevent injection risks
+
+## API Reference
+
+- `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()`
+- Array methods: `keys()`, `values()`, `entries()`
+- Properties: `first`, `last`, `max`, `size`, `ttl`, `resetTtl`
+
+## Testing
+
+- Framework: Node.js built-in test runner (`node --test`)
+- Coverage: 100%
+- Test pattern: `tests/**/*.js`
+- All tests must pass with 100% coverage before merging
+- Run: `npm test` (lint + tests) or `npm run coverage` for coverage report
+
+## Common Issues to Avoid
+
+- **Memory leaks**: When removing items from the linked list, always clear `prev`/`next` pointers to allow garbage collection
+- **LRU order pollution**: Methods like `entries()` and `values()` should access items directly rather than calling `get()`, which moves items and can delete expired items mid-iteration
+- **TTL edge cases**: Direct property access (`this.items[key]`) should be used instead of `has()` when you need to inspect expired-but-not-yet-deleted items
+- **Dead code**: Always verify edge case code is actually reachable before adding special handling
+- **Constructor assignment**: Use `let` not `const` for variables that may be reassigned (e.g., in `setWithEvicted`)
+
+## Implementation Notes
+
+- The LRU uses a doubly-linked list with `first` and `last` pointers for O(1) operations
+- TTL is stored per-item as an `expiry` timestamp; `0` means no expiration
+- `moveToEnd()` is the core method for maintaining LRU order - item is always moved to the `last` position
+- `setWithEvicted()` optimizes updates by avoiding the full `set()` path for existing keys

AGENTS.md

@@ -1059,7 +1059,7 @@ Generated by [`auto-changelog`](https://github.com/CookPete/auto-changelog).
 > 10 February 2017
 
 - Changing the signature of `remove()` to avoid edge case creation [`bb88a78`](https://github.com/avoidwork/tiny-lru/commit/bb88a78366f1ae4af209025810e0409f77ff67dc)
-- Adding some tests double checking deleting things that don't exist won''t be an  issue [`e208b76`](https://github.com/avoidwork/tiny-lru/commit/e208b7601c1b31e59ebca94cd320ad8d1b40a067)
+- Adding some tests double checking deleting things that don't exist won''t be an issue [`e208b76`](https://github.com/avoidwork/tiny-lru/commit/e208b7601c1b31e59ebca94cd320ad8d1b40a067)
 
 #### [1.4.2](https://github.com/avoidwork/tiny-lru/compare/1.4.1...1.4.2)
 

CHANGELOG.md

@@ -0,0 +1 @@
+@AGENTS.md

CLAUDE.md

@@ -0,0 +1,112 @@
+# Contributing to tiny-lru
+
+Thank you for your interest in contributing to tiny-lru! This document outlines the process for contributing to the project.
+
+## Code of Conduct
+
+This project follows the [Contributor Covenant](https://www.contributor-covenant.org/) code of conduct. By participating, you are expected to uphold this code.
+
+## Getting Started
+
+1. Fork the repository
+2. Clone your fork: `git clone https://github.com/YOUR_USERNAME/tiny-lru.git`
+3. Install dependencies: `npm install`
+4. Create a branch: `git checkout -b feature/your-feature-name`
+
+## Development
+
+### Setup
+
+```bash
+npm install
+```
+
+### Running Tests
+
+```bash
+npm test  # Run lint and tests
+npm run mocha  # Run tests with coverage
+```
+
+### Code Style
+
+- **Indentation**: Tabs
+- **Quotes**: Double quotes
+- **Semicolons**: Required
+- **Formatting**: Run `npm run fix` before committing
+
+### Linting and Formatting
+
+```bash
+npm run lint  # Check linting and formatting
+npm run fix   # Fix linting and formatting issues
+```
+
+## Making Changes
+
+### Guiding Principles
+
+- **DRY (Don't Repeat Yourself)**: Extract common logic into reusable functions
+- **YAGNI (You Ain't Gonna Need It)**: Implement only what's needed
+- **SOLID**: Follow single responsibility, open/closed, and interface segregation principles
+- **OWASP**: Prioritize security; validate inputs, avoid unsafe operations
+
+### Writing Tests
+
+- All new features must include tests
+- Maintain 100% line coverage
+- Tests live in `tests/unit/`
+- Run `npm run mocha` to verify coverage
+
+### Commit Messages
+
+Follow conventional commits:
+
+```
+type(scope): description
+
+[optional body]
+
+[optional footer]
+```
+
+**Types**: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`
+
+**Examples**:
+```
+feat: add setWithEvicted method
+fix: correct TTL expiration check
+docs: update README API reference
+```
+
+## Pull Request Process
+
+1. Ensure all tests pass: `npm test`
+2. Ensure 100% test coverage: `npm run mocha`
+3. Update documentation if needed
+4. Squash commits if necessary
+5. Submit pull request with clear description
+
+### PR Checklist
+
+- [ ] Tests pass with `npm test`
+- [ ] 100% code coverage maintained
+- [ ] Linting passes with `npm run lint`
+- [ ] Documentation updated
+- [ ] No breaking changes (or clearly documented)
+
+## Releasing
+
+Releases are managed by the maintainers. If you're preparing a release:
+
+1. Update version in `package.json`
+2. Update `CHANGELOG.md`
+3. Create release tag
+
+## Questions?
+
+Open an issue for any questions or discussions about contributions.
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the BSD-3-Clause license.