Audit: 100% coverage, private fields, dead code removal, and documentation updates

.github/CONTRIBUTING.md

@@ -0,0 +1,187 @@
+# Contributing to Haro
+
+Thank you for your interest in contributing to Haro! This document provides guidelines and instructions for contributing.
+
+## Table of Contents
+
+1. [Getting Started](#getting-started)
+2. [Development Setup](#development-setup)
+3. [Code Style](#code-style)
+4. [Testing](#testing)
+5. [Submitting Changes](#submitting-changes)
+6. [Reporting Issues](#reporting-issues)
+
+## Getting Started
+
+1. Fork the repository
+2. Clone your fork: `git clone https://github.com/your-username/haro.git`
+3. Install dependencies: `npm install`
+4. Create a branch: `git checkout -b feature/your-feature-name`
+
+## Development Setup
+
+### Requirements
+
+- Node.js >= 17.0.0
+- npm
+
+### Project Structure
+
+- `src/` - Source code
+- `tests/unit/` - Unit tests
+- `dist/` - Built distribution (generated)
+- `types/` - TypeScript definitions
+
+## Code Style
+
+This project uses **Oxlint** and **Oxfmt** for code quality and formatting:
+
+```bash
+# Check code style
+npm run lint
+
+# Fix auto-fixable issues
+npm run fix
+```
+
+### Key Guidelines
+
+- Use **tabs** for indentation
+- Use **double quotes** for strings
+- Use **camelCase** for variables and functions
+- Use **PascalCase** for classes
+- Use **UPPER_SNAKE_CASE** for constants
+- Write **JSDoc comments** for all public APIs
+- Keep functions small and focused
+
+### String Constants
+
+Use string constants from `src/constants.js` for string literals:
+
+```javascript
+// ✅ Good
+import { STRING_EMPTY } from './constants.js';
+if (str === STRING_EMPTY) { ... }
+
+// ❌ Bad
+if (str === '') { ... }
+```
+
+## Testing
+
+This project uses **Node.js native test runner**:
+
+```bash
+# Run all tests
+npm test
+
+# Run tests with coverage
+npm run coverage
+```
+
+### Writing Tests
+
+- Place unit tests in `tests/unit/`
+- Use `node:assert` for assertions
+- Follow AAA pattern (Arrange, Act, Assert)
+- Test both success and error cases
+
+Example:
+
+```javascript
+import assert from 'node:assert';
+import { describe, it } from 'node:test';
+import { Haro } from '../src/haro.js';
+
+describe('MyFeature', () => {
+    it('should do something', () => {
+        // Arrange
+        const store = new Haro();
+
+        // Act
+        const result = store.set(null, { name: 'test' });
+
+        // Assert
+        assert.ok(result);
+        assert.strictEqual(result.name, 'test');
+    });
+});
+```
+
+## Submitting Changes
+
+1. Make your changes
+2. Run tests: `npm test`
+3. Run lint: `npm run lint`
+4. Commit with clear messages
+5. Push to your fork
+6. Open a Pull Request
+
+### Commit Messages
+
+- Use present tense ("Add feature" not "Added feature")
+- Use imperative mood ("Move cursor to..." not "Moves cursor to...")
+- Be concise and descriptive
+- Reference issues when applicable
+
+### Pull Request Checklist
+
+- [ ] Tests pass (`npm test`)
+- [ ] Lint passes (`npm run lint`)
+- [ ] Code is formatted (`npm run fix`)
+- [ ] Documentation is updated if needed
+- [ ] Commit messages are clear
+
+## Reporting Issues
+
+When reporting issues, please include:
+
+- **Description**: Clear description of the issue
+- **Steps to Reproduce**: Detailed steps to reproduce
+- **Expected Behavior**: What should happen
+- **Actual Behavior**: What actually happens
+- **Environment**: Node.js version, OS, etc.
+- **Code Example**: Minimal reproducible example
+
+Example:
+
+```markdown
+## Description
+The `find()` method throws an error when passed null.
+
+## Steps to Reproduce
+1. Create a new Haro instance
+2. Call `store.find(null)`
+
+## Expected Behavior
+Should throw a descriptive error or handle null gracefully
+
+## Actual Behavior
+Throws: "Cannot read property 'length' of null"
+
+## Environment
+- Node.js: v18.0.0
+- OS: macOS 13.0
+
+## Code Example
+```javascript
+import { Haro } from 'haro';
+const store = new Haro();
+store.find(null); // Throws error
+```
+```
+
+## Code of Conduct
+
+- Be respectful and inclusive
+- Focus on constructive feedback
+- Welcome newcomers and help them learn
+- Keep discussions professional and on-topic
+
+## Questions?
+
+Feel free to open an issue for questions or discussions about contributing.
+
+---
+
+Thank you for contributing to Haro! 🎉

.husky/pre-commit

@@ -1 +1 @@
-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
+}

.oxlintrc.json

@@ -0,0 +1,8 @@
+{
+	"$schema": "./node_modules/oxlint/configuration_schema.json",
+	"ignorePatterns": ["!**/src/**", "benchmarks/**"],
+	"rules": {
+		"no-console": ["error", {"allow": ["warn", "error"]}],
+		"no-unused-vars": ["error", {"argsIgnorePattern": "^(arg|batch|data|key|override|type)$"}]
+	}
+}

AGENTS.md

@@ -0,0 +1,64 @@
+# Haro Project Guide
+
+## Overview
+Haro is a modern immutable DataStore for collections of records with indexing, versioning, and batch operations support.
+
+## Project Structure
+- `src/haro.js` - Main Haro class and factory function
+- `src/constants.js` - String and number constants
+- `tests/` - Unit tests using Node.js native test runner
+- `dist/` - Built distribution files (generated)
+- `types/haro.d.ts` - TypeScript definitions
+
+## Commands
+```bash
+npm run lint              # Lint code with oxlint
+npm run fix               # Fix linting issues with oxlint and oxfmt
+npm run test              # Run tests with Node.js test runner
+npm run coverage          # Generate coverage report
+npm run build             # Lint and build distribution files
+npm run benchmark         # Run benchmarks
+```
+
+## Code Style
+- Use tabs for indentation
+- Follow ESLint/oxlint rules (no-console, no-unused-vars)
+- Use JSDoc comments for documentation
+- Keep functions small and focused
+- Use template literals for string concatenation
+
+## Rules
+- No magic strings or magic numbers - always use constants from `src/constants.js`
+- All string literals must be defined as constants with descriptive names (e.g., `STRING_EMPTY`, `STRING_ID`)
+- All numeric literals (except 0 and 1 in simple operations) should use constants (e.g., `INT_0`, `CACHE_SIZE_DEFAULT`)
+- Constants follow naming convention: `TYPE_NAME` for strings, `TYPE_NAME` for numbers
+
+## Testing
+- Tests use Node.js native test runner (`node --test`)
+- Test files are in `tests/unit/` directory
+- Run tests: `npm test`
+- Generate coverage: `npm run coverage`
+
+## Key Conventions
+- All string literals use constants from `src/constants.js`
+- Private/internal methods start with underscore prefix
+- Lifecycle hooks follow `before*` and `on*` naming pattern
+- Return `this` for method chaining where appropriate
+- Use `Map` and `Set` for data structures
+- Immutable mode uses `Object.freeze()` for data safety
+- Adheres to DRY, YAGNI, and SOLID principles
+- Follows OWASP security guidance
+
+## Important Notes
+- The `immutable` option freezes data for immutability
+- Indexes improve query performance for `find()` and `where()` operations
+- Deep indexing with dot notation is supported (e.g., `user.profile.department`)
+- Versioning tracks historical changes when enabled
+- Batch operations are more efficient than individual operations
+- LRU caching is available for `search()` and `where()` methods (opt-in with `cache: true`)
+- Cache uses Web Crypto API for SHA-256 hash generation (requires Node.js >=19.0.0)
+- Cache keys are multi-domain: `search_HASH` or `where_HASH` format
+- Cached results are cloned/frozen to prevent mutation (respects `immutable` mode)
+- Cache invalidates on all write operations but preserves statistics
+- `search()` and `where()` are async methods - use `await` when calling
+- Cache statistics persist for the lifetime of the Haro instance

CLAUDE.md

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

LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2025, Jason Mulligan
+Copyright (c) 2026, Jason Mulligan
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without