@volt-core/node

High-performance Node.js bindings for volt-core — 12x faster parallel computation across all CPU cores.

npm install @volt-core/node

Quick Start

const Volt = require('@volt-core/node');

// Initialize thread pool (one per app)
Volt.initPool(require('os').cpus().length);

// Run async computation
const result = await Volt.compute({
  operation: 'gaussian_blur',
  data: imagePixels,
  params: { width: 1000, height: 1000 }
});

console.log(`Filtered in ${result.execution_time_ms}ms using ${result.cores_used} cores`);

API

initPool(cores?: number)

Initialize thread pool. Call once at app startup.

Volt.initPool(8); // Use 8 cores (defaults to CPU count)

info(): Promise<Object>

Get engine info.

const info = await Volt.info();
// { version: "0.1.0", cores_available: 8, supports_crypto: true }

compute(task): Promise<ComputeResult>

Run single computation task.

const result = await Volt.compute({
  operation: 'sort_parallel',
  data: [5, 2, 8, 1, 9],
  params: { /* operation-specific */ }
});

computeBatch(tasks): Promise<ComputeResult[]>

Run multiple tasks in parallel.

const results = await Volt.computeBatch([
  { operation: 'sort_parallel', data: array1 },
  { operation: 'sort_parallel', data: array2 },
  { operation: 'sort_parallel', data: array3 }
]);

Supported Operations

• gaussian_blur — Image processing with kernel
• edge_detect — Edge detection filter
• sort_parallel — Parallel merge sort
• reduce_sum — Sum reduction
• matrix_multiply — Matrix multiplication
• particle_animate — Physics simulation

Building

# Build native addon from workspace root
npm run build-native --prefix packages/node

# Or manually:
cargo build -p volt-core-node --release --manifest-path crates/volt-core-node/Cargo.toml
node packages/node/scripts/copy-native.js

Testing

# Run benchmark
npm run test --prefix packages/node

# Output: iterations, timing, ops/sec
# iterations=1000 time_ms=25 ops_s=40000.00

Troubleshooting

"Native addon not found"

• Run npm run build-native --prefix packages/node
• Ensure target/release/volt_core_node.dll (Windows) or .so (Linux) or .dylib (macOS) exists

"init_pool is not a function"

• Ensure copy script ran: node packages/node/scripts/copy-native.js
• Check packages/node/build/Release/volt_core_node.node exists

Performance

• Typical: 40K–188K ops/sec (depends on operation, input size, CPU cores)
• Overhead: <5ms per call (includes JSON serialization)
• Memory: Minimal; data passed by reference where possible

Type Definitions

interface ComputeTask {
  operation: string;
  data: number[] | string;
  params?: {
    width?: number;
    height?: number;
    scale?: number;
    kernel_size?: number;
    iterations?: number;
  };
}

interface ComputeResult {
  result: number[] | string | object;
  cores_used: number;
  execution_time_ms: number;
}

Full types in index.d.ts.

License

MIT