- Introduced `release-workflow.js` to streamline the release process:
- Automates version updates (`patch`, `minor`, `major`).
- Generates changelogs based on commit messages.
- Creates GitHub releases with autogenerated notes.
- Publishes packages to NPM.
- Enhanced documentation in `README.md` with detailed release instructions, both automated and manual.
- Updated related test cases and ensured compatibility.
**Purpose**: Simplify and standardize the release
- Introduced new test cases to validate `getChangesSince` and change log handling in `S3CompatibleStorage`.
- Verified correct logging of entity changes and retrieval based on timestamps.
- Ensured cleanup after tests to maintain test environment integrity.
**Purpose**: Strengthen test coverage for `S3CompatibleStorage` by ensuring correctness in change log functionality and timestamp-based filtering.
- Introduced `CONCURRENCY_ANALYSIS.md` to outline identified concurrency issues, including statistics handling, index synchronization, and storage contention.
- Added `CONCURRENCY_IMPLEMENTATION_SUMMARY.md` to summarize concurrency improvements, such as distributed locking and change log mechanisms.
- Created `STORAGE_CONCURRENCY_ANALYSIS.md` to evaluate concurrency risks and applied solutions for different storage adapters (`S3CompatibleStorage`, `FileSystemStorage`, `OPFSStorage`, and `MemoryStorage`).
- Updated codebase with changes related to concurrency, including distributed locking, atomic updates, event-driven synchronization, and change log support.
- Refactored tests to verify behavior of new concurrency mechanisms, including robust error handling and cleanup functions.
**Purpose**: Provides comprehensive documentation and implementation details to ensure robust concurrency handling in multi-instance, high-throughput environments.
- **Removed Files**:
- Deleted outdated statistics documentation files (`statistics.md`, `statistics-flush-solution.md`, `statistics-summary.md`) to clean up the repository and avoid confusion.
- **Added Standards**:
- Introduced `DOCUMENTATION_STANDARDS.md` to outline naming conventions and troubleshooting practices for more consistent and maintainable project documentation.
- **Tests**:
- Added a new test file `edge-cases.test.ts` to verify handling of edge cases, ensuring robust behavior against boundary values and invalid inputs.
**Purpose**: Cleans up deprecated documentation while introducing concrete standards for maintaining and updating documentation. Enhances test coverage for unusual or boundary inputs, improving overall system resilience.
- **Integration Tests**:
- Introduced `api-integration.test.ts` to validate API functionality:
- Verifies text insertion, vector embedding generation, and search operations.
- Confirms HNSW index correctness for vector similarity search.
- Ensures no dimensional mismatches in embeddings.
- **Test Server**:
- Added test server utilizing Express for endpoint simulation (`/insert` and `/search/text`).
- **Dependencies**:
- Introduced `express` and `node-fetch` as new dependencies for testing purposes.
- **Vitest Fix**:
- Updated `vitest.config.ts` to resolve the `process.memoryUsage` error by setting `logHeapUsage: false`.
- **Package Updates**:
- Modified `package-lock.json` to include newly added dependencies and updates.
**Purpose**: Guarantees the stability of core API endpoints and vector-related functionality, ensuring reliable behavior for end-to-end scenarios.
- **Tests**:
- Introduced `database-operations.test.ts` to validate core database functionalities, including initialization, CRUD operations, statistics retrieval, and search capabilities.
- Added `dimension-standardization.test.ts` to ensure vector dimension consistency (fixed at 512) throughout operations like embedding, configuration, and validation.
- Enhanced test cases to include scenarios for adding, retrieving, and handling errors for incorrect vector dimensions.
- **Documentation**:
- Created `VECTOR_DIMENSION_STANDARDIZATION.md` to detail the transition to standardizing vectors to 512 dimensions, rationale for the change, potential impacts, and migration steps.
- Includes best practices for handling vectors and utilizing the built-in embedding functions.
**Purpose**: Improve system robustness with comprehensive test coverage focusing on critical database and vector operations while providing clear documentation for developers to adapt to the standardized vector dimensions.
- **Core**:
- Added `check-database.js` to verify database status and validate search functionality.
- Created `fix-dimension-mismatch.js` to handle re-embedding of existing data to resolve dimension mismatch from 3 to 512.
- Improved test cases by updating vector operations to support 512 dimensions, replacing previously hardcoded dimensions.
- **Migration**:
- Developed `DIMENSION_MISMATCH_SUMMARY.md`, detailing the root cause, solution, and preventive strategies for dimension mismatch issues.
- Added `production-migration-guide.md` for structured production migration with detailed steps on re-embedding strategies, batching, and error handling.
- **Tests**:
- Enhanced test coverage with 512-dimensional vector validation.
- Introduced helper functions for consistent vector testing behavior and streamlined search test cases.
- **Documentation**:
- Updated project documentation to highlight the resolution process for dimension mismatches, emphasizing preventive mechanisms such as auto-migration and version tracking.
**Purpose**: Address critical dimension mismatch issues caused by embedding changes, restore functionality, and provide a roadmap for robust prevention strategies and migration processes.
- **Core**: Improved verb creation logic by adding `createdAt`, `updatedAt`, and `createdBy` attributes. These fields include timestamped metadata (`seconds`, `nanoseconds`) and source augmentation/service information for better tracking.
- **Storage**: Refactored `BaseStorage` methods to utilize internal variants (e.g., `saveVerb_internal`, `getNoun_internal`). Added support for new verb attributes while maintaining backward compatibility with existing data structures.
- **Tests**:
- Updated `s3-storage.test.ts` and `opfs-storage.test.ts` to validate changes in verb attributes such as timestamps and augmentation metadata.
- Added assertions for `createdAt`, `updatedAt`, and `createdBy` fields in test cases.
- **Cleanup**: Replaced ambiguous type aliases like `Edge` and `HNSWNode` with clearer equivalents (`Verb` and `HNSWNoun_internal`) for consistency across storage adapters.
**Purpose**: Enhance metadata tracking and standardize attribute handling across storage and core modules to ensure accurate and consistent data throughout the system.
- **Tests**: Added new `statistics-storage.test.ts` to validate statistics storage functionality across scenarios including saving, retrieving, time-based partitioning, and backward compatibility. Ensured tests dynamically handle missing environment variables by skipping S3-related tests when credentials are unavailable.
- **Docs**: Enhanced `statistics.md` with detailed explanations of scalability improvements, including adaptive flush timing, batched updates, and time-based partitioning. Improved readability and structure.
- **Storage**: Updated all storage adapters to integrate time-based partitioning and maintain backward compatibility with legacy statistics storage formats.
- **Dependencies**: Added `dotenv` to support environmental variable management for storage adapter tests.
**Purpose**: Strengthen system reliability by adding comprehensive test coverage for statistics storage, improve scalability documentation, and ensure consistency across storage adapters with robust implementations.
- **Core**: Enhanced `getStatistics` function to support `service` and `service[]` filters, enabling statistics breakdown by service. Modified return structure to include `serviceBreakdown` for detailed insights.
- **Storage**: Implemented a new `BaseStorageAdapter` abstract class to centralize statistics-related functionality, such as incrementing/decrementing counters and updating HNSW index size. Refactored all storage adapters (`FileSystemStorage`, `S3CompatibleStorage`, `MemoryStorage`, `OPFSStorage`) to extend `BaseStorageAdapter`, ensuring consistent statistics tracking.
- **Tests**: Added new test cases in `statistics.test.ts` to validate service-level statistics tracking, breakdown accuracy, and multi-service filtering.
**Purpose**: Improve insight into data trends by tracking service-specific usage in statistics. Enhance maintainability and consistency through storage adapter centralization and robust testing.
- **Core**: Introduced a new `getStatistics` utility function in `statistics.ts` for fetching database statistics at the root level of the library. Enhanced `BrainyData` methods to ensure metadata includes `id` field and refined statistics calculations, excluding verbs from the noun count.
- **Tests**: Added comprehensive test coverage in `statistics.test.ts` for the new utility function, validating proper error handling, statistics accuracy, and consistent results between instance methods and standalone function.
- **Storage Config**: Enabled dynamic support for AWS S3, Cloudflare R2, and Google Cloud Storage in web service configuration, utilizing environment variables for adapter setup. Addressed a race condition in `FileSystemStorage` initialization by deferring path module imports.
**Purpose**: Enhance database analytics by introducing a reusable `getStatistics` function, improve flexibility in storage configuration, and ensure robust testing for reliability and accuracy.
- Introduced comprehensive mock for the Origin Private File System (OPFS) in `tests/mocks/opfs-mock.ts`, simulating environment for detailed storage testing.
- Added `tests/opfs-storage.test.ts`, containing extensive test cases for `OPFSStorage` operations including metadata, nouns, verbs, and storage status.
- Improved S3 mock implementation in `tests/mocks/s3-mock.ts` with better object persistence, validation, and logging to emulate real S3 behavior.
- Resolved issues related to metadata, nouns, verbs, and storage usage inconsistencies in mock storage adapters.
- Enhanced logging and error handling to aid in debugging and test reliability.
Purpose: Improve test completeness and reliability by introducing detailed mocks and extended test cases for S3 and OPFS storage systems.
- Removed outdated test files: `test-tensorflow-import.cjs`, `test-tensorflow-import.js`, and `verify-package-size.js`.
- Introduced `tests/package-size-breakdown.test.ts` to analyze included npm package files and validate their sizes.
- Added comprehensive tests for storage adapters (`MemoryStorage`, `FileSystemStorage`, `OPFSStorage`, etc.) in `tests/storage-adapters.test.ts`.
- Improved OPFS storage mocking and test coverage for browser and Node.js environments.
- Introduced environment detection tests to ensure correct storage adapter selection.
- Created `STORAGE_TESTING.md` to document storage architecture, test coverage, and guidelines for further improvements.
Purpose: Modernize testing infrastructure and enhance storage system reliability through better test coverage and documentation.
- **Core Improvements**:
- Refactored logging functions into a unified `logger` method for consistent output across the library.
- Enabled the `forceMemoryStorage` option in `BrainyData` initialization for improved storage flexibility in tests and specific use cases.
- **TensorFlow.js and Environment Updates**:
- Clarified the dependency structure in `README.md` to emphasize bundled dependencies and remove legacy peer dependency instructions.
- Simplified and reformatted environment detection logic for better maintainability and readability.
- **Testing Enhancements**:
- Added `tests/package-size-limit.test.ts` to monitor and validate npm package size against defined thresholds.
- Updated `tests/environment.node.test.ts` and core tests to leverage `forceMemoryStorage` for better test setup standardization.
- Improved test isolation with expanded `globalThis` utility definitions and cleanup logic.
- **Documentation**:
- Added detailed best practices for debugging and organizing tests in `DEVELOPERS.md`.
- Removed outdated installation hints from `package.json` and streamlined scripts by including `test:size` for package size validation.
**Purpose**: These changes unify core logging mechanisms, expand configurability of storage options, and improve testing reliability and coverage. Documentation and clarity are enhanced to align with updated functionality and best practices.
- **Test Enhancements**:
- Refactored test setup in `core.test.ts` for better isolation and clarity:
- Added explicit `.clear()` calls to ensure clean state between tests.
- Replaced old vector addition logic with simplified data insertion methods.
- Updated search operations to reflect current functionality and debug-friendly output.
- Introduced the `@vitest-environment jsdom` annotation in `environment.browser.test.ts` for accurate browser environment emulation.
- **Configuration Updates**:
- Enhanced `vitest.config.ts`:
- Introduced custom `reporters` for cleaner and focused test result presentation.
- Expanded console log filtering with additional patterns for reducing noise from TensorFlow.js and setup processes.
- **Purpose**:
- These updates improve test clarity, consistency, and robustness while streamlining the configuration to minimize distractions in test outputs.
- **Test Improvements**:
- Introduced data-clearing steps (`.clear()`) across critical test cases for ensuring better test isolation and preventing state leakage.
- Extended support for overriding global utilities (`testUtils`) and added fallback behaviors for test vector creation.
- **Configuration Updates**:
- Added support for `distanceFunction` as an alternative to `metric` in vector operations for consistency.
- Adjusted and unified asynchronous `timeout` handling across test suites for predictability.
- **Purpose**:
- These updates improve reliability, maintainability, and clarity in test cases while ensuring compatibility across diverse test environments.
- **New Tests Added**:
- Introduced multiple test suites covering core functionalities (`core.test.ts`), vector operations (`vector-operations.test.ts`), Node.js environment (`environment.node.test.ts`), browser setup (`environment.browser.test.ts`), and TensorFlow.js-specific behaviors (`tensorflow-patch.test.ts`).
- Added performance, scalability, and error-handling tests to ensure robust validation of vector addition, search, and text embedding functionalities.
- Introduced setup utilities (`tests/setup.ts`) and standardized test utilities for creating predictable test cases.
- **Configuration**:
- Created `vitest.config.ts` for custom test configurations, including support for modern test environments (`jsdom`, `happy-dom`) and extended timeouts for asynchronous operations.
- **Validation**:
- Includes compatibility checks for TensorFlow.js imports and ensures proper handling of `TextEncoder`/`TextDecoder` in Node.js environments.
This commit significantly enhances the testing coverage and structure, ensuring Brainy functionality is robust, cross-platform, and aligned with evolving reliability standards.
