[](LICENSE)
-[](https://nodejs.org/)
+[](https://nodejs.org/)
[](https://www.typescriptlang.org/)
[](CONTRIBUTING.md)
[](https://www.npmjs.com/package/@soulcraft/brainy)
@@ -1264,7 +1264,27 @@ comprehensive [Scaling Strategy](scalingStrategy.md) document.
## Requirements
-- Node.js >= 23.11.0
+- Node.js >= 24.0.0
+
+### Node.js 24 Optimizations
+
+Brainy takes advantage of several optimizations available in Node.js 24:
+
+1. **Improved Worker Threads Performance**: The multithreading system has been completely rewritten to leverage Node.js 24's enhanced Worker Threads API, resulting in better performance for compute-intensive operations like embedding generation and vector similarity calculations.
+
+2. **Worker Pool Management**: A sophisticated worker pool system reuses worker threads to minimize the overhead of creating and destroying threads, leading to more efficient resource utilization.
+
+3. **Dynamic Module Imports**: Uses the new `node:` protocol prefix for importing core modules, which provides better performance and more reliable module resolution.
+
+4. **ES Modules Optimizations**: Takes advantage of Node.js 24's improved ESM implementation for faster module loading and execution.
+
+5. **Enhanced Error Handling**: Implements more robust error handling patterns available in Node.js 24 for better stability and debugging.
+
+These optimizations are particularly beneficial for:
+- Large-scale vector operations
+- Batch processing of embeddings
+- Real-time data processing pipelines
+- High-throughput search operations
## Contributing
diff --git a/THREADING.md b/THREADING.md
new file mode 100644
index 00000000..632c594a
--- /dev/null
+++ b/THREADING.md
@@ -0,0 +1,183 @@
+# Brainy Threading Implementation
+
+This document explains how Brainy's threading implementation works across different environments.
+
+## Overview
+
+Brainy uses a unified threading approach that adapts to the environment it's running in:
+
+1. **Node.js**: Uses Worker Threads API (optimized for Node.js 24+)
+2. **Browser**: Uses Web Workers API
+3. **Fallback**: Executes on the main thread when neither Worker Threads nor Web Workers are available
+
+This implementation ensures that compute-intensive operations (like embedding generation and vector calculations) can be performed efficiently without blocking the main thread, while maintaining compatibility across all environments.
+
+## Implementation Details
+
+### Environment Detection
+
+Brainy automatically detects the environment it's running in:
+
+```typescript
+// From unified.ts
+export const environment = {
+ isBrowser: typeof window !== 'undefined',
+ isNode: typeof process !== 'undefined' && process.versions && process.versions.node,
+ isServerless: typeof window === 'undefined' &&
+ (typeof process === 'undefined' || !process.versions || !process.versions.node)
+}
+```
+
+Additional environment detection functions are available in `src/utils/environment.ts`:
+
+```typescript
+// Check if threading is available
+export function isThreadingAvailable(): boolean {
+ return areWebWorkersAvailable() || areWorkerThreadsAvailable();
+}
+
+// Check if Web Workers are available (browser)
+export function areWebWorkersAvailable(): boolean {
+ return isBrowser() && typeof Worker !== 'undefined';
+}
+
+// Check if Worker Threads are available (Node.js)
+export function areWorkerThreadsAvailable(): boolean {
+ if (!isNode()) return false;
+ try {
+ require('worker_threads');
+ return true;
+ } catch (e) {
+ return false;
+ }
+}
+```
+
+### Thread Execution
+
+The core of the threading implementation is the `executeInThread` function in `src/utils/workerUtils.ts`:
+
+```typescript
+export function executeInThread(fnString: string, args: any): Promise {
+ if (environment.isNode) {
+ return executeInNodeWorker(fnString, args)
+ } else if (environment.isBrowser && typeof window !== 'undefined' && window.Worker) {
+ return executeInWebWorker(fnString, args)
+ } else {
+ // Fallback to main thread execution
+ try {
+ const fn = new Function('return ' + fnString)()
+ return Promise.resolve(fn(args) as T)
+ } catch (error) {
+ return Promise.reject(error)
+ }
+ }
+}
+```
+
+This function:
+1. Checks if it's running in Node.js and uses Worker Threads if available
+2. Checks if it's running in a browser and uses Web Workers if available
+3. Falls back to executing on the main thread if neither is available
+
+### Node.js Implementation
+
+For Node.js environments, Brainy uses the Worker Threads API with optimizations for Node.js 24:
+
+```typescript
+function executeInNodeWorker(fnString: string, args: any): Promise {
+ // Implementation using Node.js Worker Threads
+ // Includes worker pool management for better performance
+ // Uses dynamic imports with the 'node:' protocol prefix
+ // ...
+}
+```
+
+Key optimizations:
+- Worker pool to reuse workers and minimize overhead
+- Dynamic imports with the `node:` protocol prefix
+- Error handling and cleanup
+
+### Browser Implementation
+
+For browser environments, Brainy uses the Web Workers API:
+
+```typescript
+function executeInWebWorker(fnString: string, args: any): Promise {
+ // Implementation using browser Web Workers
+ // Creates a blob URL for the worker code
+ // Handles message passing and error handling
+ // ...
+}
+```
+
+Key features:
+- Creates workers using Blob URLs
+- Proper cleanup of resources (terminating workers and revoking URLs)
+- Error handling
+
+### Fallback Mechanism
+
+When neither Worker Threads nor Web Workers are available, Brainy falls back to executing on the main thread:
+
+```typescript
+// Fallback to main thread execution
+try {
+ const fn = new Function('return ' + fnString)()
+ return Promise.resolve(fn(args) as T)
+} catch (error) {
+ return Promise.reject(error)
+}
+```
+
+This ensures that Brainy works in all environments, even if threading is not available.
+
+## Usage
+
+The threading implementation is used throughout Brainy, particularly for compute-intensive operations like embedding generation:
+
+```typescript
+export function createThreadedEmbeddingFunction(
+ model: EmbeddingModel
+): EmbeddingFunction {
+ const embeddingFunction = createEmbeddingFunction(model)
+
+ return async (data: any): Promise => {
+ // Convert the embedding function to a string
+ const fnString = embeddingFunction.toString()
+
+ // Execute the embedding function in a thread
+ return await executeInThread(fnString, data)
+ }
+}
+```
+
+## Testing
+
+Two test scripts are provided to verify the threading implementation:
+
+1. `demo/test-browser-worker.html`: Tests the threading implementation in a browser environment
+2. `demo/test-fallback.html`: Tests the fallback mechanism when threading is not available
+
+To run these tests:
+1. Build the project: `npm run build`
+2. Start a local server: `npx http-server`
+3. Open the test pages in a browser:
+ - http://localhost:8080/demo/test-browser-worker.html
+ - http://localhost:8080/demo/test-fallback.html
+
+## Compatibility
+
+The threading implementation has been tested and works in:
+
+- Node.js 24+ (using Worker Threads)
+- Modern browsers (using Web Workers):
+ - Chrome
+ - Firefox
+ - Safari
+ - Edge
+- Environments without threading support (using fallback mechanism)
+
+## Conclusion
+
+Brainy's threading implementation provides efficient execution of compute-intensive operations across all environments, with optimizations for Node.js 24 and modern browsers, and a fallback mechanism for environments where threading is not available.
diff --git a/demo/test-browser-worker.html b/demo/test-browser-worker.html
new file mode 100644
index 00000000..ccf36745
--- /dev/null
+++ b/demo/test-browser-worker.html
@@ -0,0 +1,104 @@
+
+
+
+
+
+ Brainy Browser Worker Test
+
+
+
+
Brainy Browser Worker Test
+
This page tests the Brainy worker thread implementation in a browser environment.