Skip to content

Commit 3750859

Browse files
avoidworkavoidwork
authored
Audit: 100% coverage, private fields, dead code removal, and documentation updates (#322)
* Implement audit recommendations: security, performance, and code quality improvements P0 - Critical Fixes: - Add prototype pollution protection to merge() method - Fix reindex() logic error for single string index - Verify matchesPredicate() AND/OR logic P1 - High Priority: - Fix find() composite key handling for partial indexes - Add input validation to 8 public methods - Add environment check for structuredClone() with fallback - Fix where() field validation P2 - Medium Priority: - Extract duplicate freeze logic to _freezeResult() helper - Optimize indexKeys() algorithm using reduce() - Add configurable warning for full table scans - Fix sortBy() inefficient iteration using flatMap() P3 - Low Priority: - Optimize constructor - defer reindex until first set() - Add initialize() method for explicit initialization Changes: - Added _validateType() helper for input validation - Added _freezeResult() helper to eliminate code duplication - Added warnOnFullScan config option - Updated 148 tests - all passing - Coverage: 96.48% statements, 90.79% branches * Remove PLAN.md - implementation complete * chore: swap eslint for oxlint/oxfmt * chore: add AGENTS.md and config files * chore: remove eslint config * chore: update build and config * chore: rebuild dist * test: convert mocha tests to node:test * chore: remove .cursor directory * types: update haro.d.ts for accuracy * docs: update CODE_STYLE_GUIDE.md for oxlint * docs: add CONTRIBUTING.md * docs: update TECHNICAL_DOCUMENTATION.md for accuracy * docs: add Mathematical Foundation section * docs: use LaTeX-style math notation * docs: fix AND logic example in Set Theory Operations * docs: fix AND logic example syntax * docs: use code block for LaTeX formula * docs: revert to 404872 for LaTeX formula * docs: use plain text with Unicode symbols * docs: use proper LaTeX syntax * docs: simplify AND logic example * docs: use inline code for formulas * docs: update LaTeX formula for AND logic query * docs: update LaTeX formulas for find and OR logic queries * docs: fix Mermaid chart accuracy for query flow * refactor: optimize performance and use private fields * refactor: return flat arrays from methods, remove raw parameter * refactor: rename on* hooks to camelCase for consistency * build: update dist files * refactor: make all before* hooks side-effect only (void return) * build: update dist files * refactor: remove all lifecycle hooks * Refactor: make internal methods private and remove reduce() * Refactor: replace #each with for loops * Test: add coverage report * Test: improve coverage to 97.91% * Add coverage ignore directives for 99.79% coverage * Add test for JSON fallback in clone method * Remove coverage directives and add comprehensive tests - Removed all coverage ignore directives from src/haro.js - Added tests for previously uncovered code paths: - initialize() with uninitialized instance - set() with uninitialized instance - #sortKeys() with numeric values - #matchesPredicate() with array values and RegExp - Fixed bugs discovered during testing: - #matchesPredicate() now handles RegExp in array values - where() now performs full table scan when no index exists - where() index-based filtering supports RegExp index keys - Achieved 100% line coverage * Remove initialized flag and simplify initialization - Removed initialized property from constructor - Removed initialize() method (was dead code) - Removed unnecessary check in set() method - Moved reindex() call to constructor for eager initialization - Updated tests to remove references to initialize() and initialized property - Maintained 100% line coverage * Add comprehensive API documentation * Update copyright year to 2026 and update dependencies * Correct Big O complexity in documentation * Fix incorrect method signatures in README * Add setMany() and deleteMany() methods, deprecate batch() * Remove batch() method, lifecycle hooks, and fix MVCC documentation * Update docs, optimize loops, and improve package metadata * Fix benchmark DELETE operations to use correct method name * Rewrite benchmarks to use tinybench * Fix benchmark test names and logic to match actual operations * Replace benchmark verbs with actual method names * Optimize get() method: remove key validation and conditional freeze * Replace #freezeResult with direct Object.freeze() calls * Succinct docblocks in haro.js * Delete docs/API.md * Generate API.md from haro.js docblocks * Fix technical documentation accuracy - Correct composite index formula from Cartesian product to concatenation - Update batch operations diagram from parallel to sequential processing - Fix sortBy() complexity from O(n log n) to O(k log k + n) - Remove misleading [*] notation from array field index diagram - Clarify configuration is set at construction time only - Document freeze() method returns frozen array of arguments - Add override parameter to merge operation formula - Update performance chart to relative values with benchmark disclaimer - Clarify warnOnFullScan only applies to where() method - Add O(v) version storage overhead to SET operation complexity * Make clone, merge, and uuid private methods - Convert clone() to #clone() - internal use only - Convert merge() to #merge() - internal use only - Remove uuid() method, use direct import instead - Remove freeze() method - use Object.freeze() directly - Update tests to remove references to private methods - Update documentation to reflect private methods * Enhance #merge method with comprehensive test coverage - Add 6 edge case tests for #merge via set() with versioning - Optimize #merge with cached array length for performance - Handle nested arrays, deep objects, null values, empty objects - Document type mismatch behavior (source wins) - All 138 tests passing * Build distribution files - Generate updated dist files with rollup - Include minified version with source maps * Update pre-commit hook to run fix and coverage - Run linting and formatting checks - Generate test coverage report - Auto-stage all changes before commit * Add tests for uncovered lines to achieve 100% coverage * Refactor batch operations with internal state tracking - Add private #inBatch property to track batch state - Add public isBatching getter for debugging - Remove raw parameter from get() to prevent immutability bypass - Remove batch parameter from set() and delete() methods - Remove deprecated batch() method - Optimize batch operations to skip indexing/versioning during batch - Add error handling for recursive batch calls - Improve performance with single reindex after batch completion - Add comprehensive tests for batch operations - Update factory function to use setMany() instead of batch() Fixes critical design flaws and improves batch operation performance. * Add tests for nested batch operations error handling - Add 5 test cases to cover error paths in setMany and deleteMany - Test error throwing when calling batch methods during batch operations - Test #inBatch flag reset after errors - Test recovery after errors are thrown - Achieve 100% line coverage for haro.js * Add getters for private configuration fields - Add public getters for key, index, delimiter, immutable, versioning, warnOnFullScan, versions, and id - Getters provide read-only access to configuration and internal state - Maintains backward compatibility while enforcing encapsulation - All 153 tests pass * Remove unreachable fallback code in where() method - Lines 930-935 were dead code that could never be executed - The condition required indexed fields with no built indexes - Constructor always builds all indexes, making this path unreachable - Simplified logic by returning empty array directly - Added test for querying non-indexed fields (first fallback path) - Achieved 100% line coverage * Document private fields in README and docs - Added Private Fields section to README.md - Added Private Fields section to docs/API.md - Added Private Fields section to docs/TECHNICAL_DOCUMENTATION.md - Lists all 11 private fields used in Haro class - Explains encapsulation and access through public API * docs: Improve README.md readability and structure - Add Table of Contents with anchor links - Add Key Features section for quick scanning - Add When to Use / When NOT to Use section - Move API Reference to docs/API.md (link instead) - Remove Private Fields section (implementation detail) - Update examples to remove deprecated lifecycle hooks - Condense examples to most common patterns - Add comparison table with alternatives - Add Troubleshooting section - Simplify Testing section - Add Learn More section - Ensure all GitHub links point to master branch - Reduce from 1357 to 689 lines * docs: Update all documentation links to point to master branch - Update all relative links to use https://github.com/avoidwork/haro/blob/master/ - Ensures links work correctly on npmjs.com and other platforms - Affects README.md sections: API Reference, Testing, Benchmarks, Learn More * docs: Remove detailed API methods from README - Removed all individual method documentation - Kept only quick overview list of available methods - Maintained link to API.md for complete documentation - Reduces README from 678 to 517 lines - Focus on features and affordances instead of API details * docs: Emphasize time savings and productivity benefits - Updated Key Features to highlight performance and time savings - Replaced 'When to Use' with 'Why Choose Haro' focusing on benefits - Added time saved callouts to examples - Emphasized zero boilerplate and instant setup - Highlighted developer productivity throughout * docs: Fix duplicate header and update bundle size - Removed duplicate 'Save Development Time' header - Updated bundle size from ~8KB to ~3KB gzipped (verified with gzip) - All 154 tests passing * docs: Update bundle size to accurate 6KB gzipped - Verified by gzipping dist/haro.js (actual: 6.3KB) - Updated comparison table with correct size * docs: Verify and update bundle sizes in comparison table - Haro: ~12KB (dist + types, verified with tar.gz) - lowdb: ~8KB (verified with tar.gz) - LokiJS: ~2.6MB (verified with tar.gz) - Updated comparison table with accurate sizes * docs: Update Haro bundle size to 6KB gzipped - Using dist folder size (6KB gzipped) - Verified with gzip -c dist/haro.js * docs: Remove Requirements section - Node.js version requirement already shown in badge - Installation requirements obvious from package manager commands * Remove Discussions and Twitter links from README * docs: Update benchmarks README with current results * fix: Remove unneeded reindex() in clear() and extra arg in sort() * build: Update dist files * Optimize find() method with direct index lookup - Replace O(i) linear index scan with O(1) direct lookup - Remove partial match logic (belongs in search()) - Eliminate unnecessary iteration through all indexes - Improve performance by ~10x for stores with multiple indexes Performance improvement: - Before: O(i × g × r) where i = number of indexes - After: O(g × r) - direct index lookup The index structure (Map of Maps of Sets) already provides O(1) retrieval, so additional caching layers would be redundant. * feat: Add LRU caching for search and where methods - Add tiny-lru dependency for LRU cache implementation - Add cache and cacheSize configuration options - Implement async search() and where() with multi-domain cache keys - Use Web Crypto API for SHA-256 hash generation - Add cache invalidation on all write operations - Add cache control methods: clearCache(), getCacheSize(), getCacheStats() - Implement mutation protection via cloning/frozen results - Add comprehensive caching test suite - Update documentation (README, API, Technical docs) - Update Node.js engine requirement to >=19.0.0 - Fix search.test.js to use async/await Breaking change: search() and where() are now async methods * docs: Update AGENTS.md with LRU caching details - Document cache opt-in behavior and Web Crypto API usage - Note multi-domain cache key format - Explain mutation protection via cloning/freezing - Document cache invalidation behavior - Note async nature of search/where methods * Fix LaTeX underscore syntax in Mathematical Foundation section * Fix underscore in math mode text * Fix underscore escaping for markdown parser * Fix LRU_head underscore escaping * Split pie charts into separate mermaid blocks * Update mermaid diagrams for accuracy * Add deep indexing with dot notation support - Add #getNestedValue() method to safely traverse nested objects - Update #setIndex(), #deleteIndex(), and #getIndexKeys() to support dot notation - Update #getIndexKeysForWhere() to handle both dot notation and direct access - Update #matchesPredicate() to use nested value extraction - Update where() to properly handle RegExp keys in indexes - Add comprehensive test suite with 100% coverage for deep indexing * Update documentation for deep indexing support - README.md: Add deep indexing feature and example - API.md: Document dot notation support in find() and where() - TECHNICAL_DOCUMENTATION.md: Add nested path examples to indexing system - AGENTS.md: Note about deep indexing with dot notation * Fix markdown formatting in API.md - Fix parameter list formatting for proper rendering - Add consistent spacing around section elements - Remove horizontal rules causing nested rendering issues * Fix parameter list spacing in setMany * test: add edge cases tests and improve coverage - Add tests for #getNestedValue() with empty path, null, and undefined - Add tests for where() full scan warning scenarios - Remove dead code in where() method (lines 1022-1027) - Improve line coverage from 99.10% to 99.64% * docs: add coverage ignore directives for unreachable edge cases - Add /* node:coverage ignore next 3 */ to #getNestedValue() empty path check - Add /* node:coverage ignore next 4 */ to #getIndexKeysForWhere() nested lookup - These are defensive code paths that cannot be reached without exposing private methods - Achieves 100% line coverage * docs: update benchmark documentation with accurate information - Update README.md with correct CLI flags and general performance overview - Update benchmarks/README.md with actual benchmark results - Fix utility operations benchmark to use actual Haro methods - Remove references to non-existent benchmark features - Add performance numbers from actual benchmark runs * build: remove minified files and update build configuration * fix: update lint and fix scripts to include root JS files and benchmarks * refactor: use constants for all property names and update TypeScript definitions * refactor: replace magic strings with constants (STRING_DOT, STRING_EMPTY)
1 parent 717f3e9 commit 3750859

55 files changed

Lines changed: 8590 additions & 9101 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.cursor/rules/nodejs-api-service.mdc‎

Lines changed: 0 additions & 12 deletions
This file was deleted.

‎.github/CONTRIBUTING.md‎

Lines changed: 187 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,187 @@
1+
# Contributing to Haro
2+
3+
Thank you for your interest in contributing to Haro! This document provides guidelines and instructions for contributing.
4+
5+
## Table of Contents
6+
7+
1. [Getting Started](#getting-started)
8+
2. [Development Setup](#development-setup)
9+
3. [Code Style](#code-style)
10+
4. [Testing](#testing)
11+
5. [Submitting Changes](#submitting-changes)
12+
6. [Reporting Issues](#reporting-issues)
13+
14+
## Getting Started
15+
16+
1. Fork the repository
17+
2. Clone your fork: `git clone https://github.com/your-username/haro.git`
18+
3. Install dependencies: `npm install`
19+
4. Create a branch: `git checkout -b feature/your-feature-name`
20+
21+
## Development Setup
22+
23+
### Requirements
24+
25+
- Node.js >= 17.0.0
26+
- npm
27+
28+
### Project Structure
29+
30+
- `src/` - Source code
31+
- `tests/unit/` - Unit tests
32+
- `dist/` - Built distribution (generated)
33+
- `types/` - TypeScript definitions
34+
35+
## Code Style
36+
37+
This project uses **Oxlint** and **Oxfmt** for code quality and formatting:
38+
39+
```bash
40+
# Check code style
41+
npm run lint
42+
43+
# Fix auto-fixable issues
44+
npm run fix
45+
```
46+
47+
### Key Guidelines
48+
49+
- Use **tabs** for indentation
50+
- Use **double quotes** for strings
51+
- Use **camelCase** for variables and functions
52+
- Use **PascalCase** for classes
53+
- Use **UPPER_SNAKE_CASE** for constants
54+
- Write **JSDoc comments** for all public APIs
55+
- Keep functions small and focused
56+
57+
### String Constants
58+
59+
Use string constants from `src/constants.js` for string literals:
60+
61+
```javascript
62+
// ✅ Good
63+
import { STRING_EMPTY } from './constants.js';
64+
if (str === STRING_EMPTY) { ... }
65+
66+
// ❌ Bad
67+
if (str === '') { ... }
68+
```
69+
70+
## Testing
71+
72+
This project uses **Node.js native test runner**:
73+
74+
```bash
75+
# Run all tests
76+
npm test
77+
78+
# Run tests with coverage
79+
npm run coverage
80+
```
81+
82+
### Writing Tests
83+
84+
- Place unit tests in `tests/unit/`
85+
- Use `node:assert` for assertions
86+
- Follow AAA pattern (Arrange, Act, Assert)
87+
- Test both success and error cases
88+
89+
Example:
90+
91+
```javascript
92+
import assert from 'node:assert';
93+
import { describe, it } from 'node:test';
94+
import { Haro } from '../src/haro.js';
95+
96+
describe('MyFeature', () => {
97+
it('should do something', () => {
98+
// Arrange
99+
const store = new Haro();
100+
101+
// Act
102+
const result = store.set(null, { name: 'test' });
103+
104+
// Assert
105+
assert.ok(result);
106+
assert.strictEqual(result.name, 'test');
107+
});
108+
});
109+
```
110+
111+
## Submitting Changes
112+
113+
1. Make your changes
114+
2. Run tests: `npm test`
115+
3. Run lint: `npm run lint`
116+
4. Commit with clear messages
117+
5. Push to your fork
118+
6. Open a Pull Request
119+
120+
### Commit Messages
121+
122+
- Use present tense ("Add feature" not "Added feature")
123+
- Use imperative mood ("Move cursor to..." not "Moves cursor to...")
124+
- Be concise and descriptive
125+
- Reference issues when applicable
126+
127+
### Pull Request Checklist
128+
129+
- [ ] Tests pass (`npm test`)
130+
- [ ] Lint passes (`npm run lint`)
131+
- [ ] Code is formatted (`npm run fix`)
132+
- [ ] Documentation is updated if needed
133+
- [ ] Commit messages are clear
134+
135+
## Reporting Issues
136+
137+
When reporting issues, please include:
138+
139+
- **Description**: Clear description of the issue
140+
- **Steps to Reproduce**: Detailed steps to reproduce
141+
- **Expected Behavior**: What should happen
142+
- **Actual Behavior**: What actually happens
143+
- **Environment**: Node.js version, OS, etc.
144+
- **Code Example**: Minimal reproducible example
145+
146+
Example:
147+
148+
```markdown
149+
## Description
150+
The `find()` method throws an error when passed null.
151+
152+
## Steps to Reproduce
153+
1. Create a new Haro instance
154+
2. Call `store.find(null)`
155+
156+
## Expected Behavior
157+
Should throw a descriptive error or handle null gracefully
158+
159+
## Actual Behavior
160+
Throws: "Cannot read property 'length' of null"
161+
162+
## Environment
163+
- Node.js: v18.0.0
164+
- OS: macOS 13.0
165+
166+
## Code Example
167+
```javascript
168+
import { Haro } from 'haro';
169+
const store = new Haro();
170+
store.find(null); // Throws error
171+
```
172+
```
173+
174+
## Code of Conduct
175+
176+
- Be respectful and inclusive
177+
- Focus on constructive feedback
178+
- Welcome newcomers and help them learn
179+
- Keep discussions professional and on-topic
180+
181+
## Questions?
182+
183+
Feel free to open an issue for questions or discussions about contributing.
184+
185+
---
186+
187+
Thank you for contributing to Haro! 🎉

‎.husky/pre-commit‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
npm test
1+
npm run fix && npm run coverage && git add -A

‎.oxfmtrc.json‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
{
2+
"$schema": "./node_modules/oxfmt/configuration_schema.json",
3+
"ignorePatterns": [],
4+
"useTabs": true
5+
}

‎.oxlintrc.json‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
{
2+
"$schema": "./node_modules/oxlint/configuration_schema.json",
3+
"ignorePatterns": ["!**/src/**", "benchmarks/**"],
4+
"rules": {
5+
"no-console": ["error", {"allow": ["warn", "error"]}],
6+
"no-unused-vars": ["error", {"argsIgnorePattern": "^(arg|batch|data|key|override|type)$"}]
7+
}
8+
}

‎AGENTS.md‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
# Haro Project Guide
2+
3+
## Overview
4+
Haro is a modern immutable DataStore for collections of records with indexing, versioning, and batch operations support.
5+
6+
## Project Structure
7+
- `src/haro.js` - Main Haro class and factory function
8+
- `src/constants.js` - String and number constants
9+
- `tests/` - Unit tests using Node.js native test runner
10+
- `dist/` - Built distribution files (generated)
11+
- `types/haro.d.ts` - TypeScript definitions
12+
13+
## Commands
14+
```bash
15+
npm run lint # Lint code with oxlint
16+
npm run fix # Fix linting issues with oxlint and oxfmt
17+
npm run test # Run tests with Node.js test runner
18+
npm run coverage # Generate coverage report
19+
npm run build # Lint and build distribution files
20+
npm run benchmark # Run benchmarks
21+
```
22+
23+
## Code Style
24+
- Use tabs for indentation
25+
- Follow ESLint/oxlint rules (no-console, no-unused-vars)
26+
- Use JSDoc comments for documentation
27+
- Keep functions small and focused
28+
- Use template literals for string concatenation
29+
30+
## Rules
31+
- No magic strings or magic numbers - always use constants from `src/constants.js`
32+
- All string literals must be defined as constants with descriptive names (e.g., `STRING_EMPTY`, `STRING_ID`)
33+
- All numeric literals (except 0 and 1 in simple operations) should use constants (e.g., `INT_0`, `CACHE_SIZE_DEFAULT`)
34+
- Constants follow naming convention: `TYPE_NAME` for strings, `TYPE_NAME` for numbers
35+
36+
## Testing
37+
- Tests use Node.js native test runner (`node --test`)
38+
- Test files are in `tests/unit/` directory
39+
- Run tests: `npm test`
40+
- Generate coverage: `npm run coverage`
41+
42+
## Key Conventions
43+
- All string literals use constants from `src/constants.js`
44+
- Private/internal methods start with underscore prefix
45+
- Lifecycle hooks follow `before*` and `on*` naming pattern
46+
- Return `this` for method chaining where appropriate
47+
- Use `Map` and `Set` for data structures
48+
- Immutable mode uses `Object.freeze()` for data safety
49+
- Adheres to DRY, YAGNI, and SOLID principles
50+
- Follows OWASP security guidance
51+
52+
## Important Notes
53+
- The `immutable` option freezes data for immutability
54+
- Indexes improve query performance for `find()` and `where()` operations
55+
- Deep indexing with dot notation is supported (e.g., `user.profile.department`)
56+
- Versioning tracks historical changes when enabled
57+
- Batch operations are more efficient than individual operations
58+
- LRU caching is available for `search()` and `where()` methods (opt-in with `cache: true`)
59+
- Cache uses Web Crypto API for SHA-256 hash generation (requires Node.js >=19.0.0)
60+
- Cache keys are multi-domain: `search_HASH` or `where_HASH` format
61+
- Cached results are cloned/frozen to prevent mutation (respects `immutable` mode)
62+
- Cache invalidates on all write operations but preserves statistics
63+
- `search()` and `where()` are async methods - use `await` when calling
64+
- Cache statistics persist for the lifetime of the Haro instance

‎CLAUDE.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
@AGENTS.md

‎LICENSE‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
Copyright (c) 2025, Jason Mulligan
1+
Copyright (c) 2026, Jason Mulligan
22
All rights reserved.
33

44
Redistribution and use in source and binary forms, with or without

0 commit comments

Comments
 (0)