Install

npm install vectrojs

Vectro is plain JavaScript plus WebAssembly that it generates as it runs. There is no native addon, no install script and no dependency, so the same package installs on Linux, macOS and Windows, and nothing has to be compiled on the machine. Node needs to be version 20 or later.

Check that it runs

import { Engine, canCompileWasm } from 'vectrojs';

const engine = new Engine();
const t = engine.table({ x: [1, 2, 3, 4] });

console.log('sum of x:', t.sum('x'));
console.log('compiles WebAssembly:', canCompileWasm());

await engine.close();

canCompileWasm() says whether the runtime lets Vectro build a kernel per query. Node and browsers do. Cloudflare Workers don’t, which is why the edge build ships a precompiled module (see On the edge).

Entry points

One package, one import per kind of runtime. The table and query API is the same in all of them.

Import	Use it in	Threads
vectrojs	Node 20+	Worker threads on every core, sharing one block of memory
vectrojs/browser	Web pages	Web Workers on every core when the page is cross-origin isolated, one thread otherwise; SplitEngine for multi-core pages without isolation
vectrojs/portable	Cloudflare Workers, Deno, Bun, any runtime without Node APIs	One thread, plain memory
vectrojs/serve	Node servers	The HTTP, OData, PostgreSQL and Arrow Flight SQL servers
vectrojs/dist/vectro.wasm	Runtimes that can’t compile WebAssembly	The precompiled kernels (11 KB) to pass to the portable engine

import { Engine, sql } from 'vectrojs';                  // Node
import { Engine, SplitEngine } from 'vectrojs/browser';  // pages
import { Engine } from 'vectrojs/portable';              // edge

Each entry also exports sql, Table, VectorIndex, DistinctSketch, the Arrow readers and writers and the dataset helpers. The Node entry adds SplitEngine, Emitter and file reading (engine.readCSV(path), datasets on disk).

How many threads

new Engine() uses every core the machine reports. Pass threads to use fewer:

import { Engine } from 'vectrojs';

const engine = new Engine({ threads: 2 });   // the calling thread plus one worker
const t = engine.table({ price: Float64Array.from({ length: 1_000_000 }, (_, i) => i % 1000) });
console.log(t.filter('price > 500').count());
await engine.close();

The thread that calls a query does part of the work itself, so threads: 2 starts one worker thread. Small inputs (under roughly 100,000 rows for most operations) run on the calling thread alone, because waking the other threads would cost more than it saves.

Closing an engine

await engine.close() stops the worker threads. The workers don’t keep Node alive, so a script that forgets to close still exits; close engines anyway in servers and tests that create more than one.

The command line

The package installs two commands:

npx vectro serve --root ./data --pg 5433   # every CSV, Arrow and .vectro file in ./data as a table
npx vectro-mcp                              # the MCP server for AI assistants

vectro serve answers SQL over HTTP on port 8787 and, with --pg, over the PostgreSQL protocol, so psql, Power BI, Tableau, Metabase and Grafana can connect. See Serving, BI tools and MCP server.

What’s stable

This is version 0.1.0, the first release.

Part	Status
Tables, filters, group by, joins, sort; CSV, Arrow and JSON lines	Stable: answers checked against plain JavaScript and DuckDB
SQL	Stable for what the SQL page lists; anything else gives a clear error
Datasets bigger than memory (.vectro files)	Stable; the file format may still change before 1.0
vectro serve	Beta: checked with the drivers BI tools use, not yet with every application
Streams, vector search, MCP server	Experimental: the API may change

Next: the quick start.