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

.husky/pre-commit

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

.oxfmtrc.json

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

AGENTS.md

@@ -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

CHANGELOG.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)
 

CLAUDE.md

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

CONTRIBUTING.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.