​

TuringDB JavaScript SDK

The turingdb npm package runs in Node.js 18 or later and in the browser, and ships with TypeScript declarations. See Get Started for a first walkthrough, including the setup for a web page.

npm install turingdb

Install the package version that matches your server: turingdb@3.1 for a TuringDB 3.1 server.

​

TuringClient

import { TuringClient } from "turingdb";

const client = new TuringClient({
    url: "http://localhost:6686/query",
    graph: "people",
});

Creating a client opens no connection: each query is a separate request to url. The decoder is compiled on the first query and shared by every client in the process or the page.

​

Methods

Each query takes these options:

const controller = new AbortController();
setTimeout(() => controller.abort(), 5000);

// rejects with an AbortError if it runs longer than 5 seconds
await client.query("MATCH (n) RETURN count(n)", {
    signal: controller.signal,
});

​

Results

query() resolves to the result’s chunks and the server-side execution time:

{
    chunks: { names: string[]; columns: Column[] }[];
    execTimeMs: number | null;
}

A result streams in chunks of up to 65,536 rows, and each chunk holds every column of its rows. A result with no rows is one chunk of empty columns, so RETURN a, b matching nothing gives [[[], []]] from queryData().

const { chunks } = await client.query(
    "MATCH (p:Person) RETURN p.name AS name, p.age AS age",
);

for (const { names, columns } of chunks) {
    const [name, age] = columns;
    for (let row = 0; row < name.length; row++) {
        console.log(name.get(row), age.get(row));   // 'Marie' 33n
    }
}

​

Column

values reads a large numeric column without building a JavaScript value per row. A row that holds null reads as 0 there, so check validity:

const { chunks } = await client.query(
    "MATCH (p:Person) RETURN p.age ORDER BY p.age",
);
const ages = chunks[0].columns[0];

ages.values;      // BigInt64Array [ 33n, 0n, 0n ]
ages.validity;    // Uint8Array [ 1 ]: only row 0 holds a value
ages.toArray();   // [ 33n, null, null ]

​

Value types

To turn a DateTime into a JavaScript Date, which holds milliseconds:

const { chunks } = await client.query(
    "RETURN datetime('2024-03-15T10:30:00Z') AS d",
);
const micros = chunks[0].columns[0].get(0);   // 1710498600000000n
new Date(Number(micros / 1000n));   // 2024-03-15T10:30:00.000Z

​

Parameters

query(cypher, { parameters }) binds each $name in the query to parameters.name. A parameter can stand for a value anywhere an expression goes, or for a label or an edge type (see Query parameters):

await client.query(
    "MATCH (p:Person) WHERE p.age >= $age RETURN p.name",
    { parameters: { age: 30 } },
);

// a write, so inside a change (see Versioning below)
const rows = [
    { name: "Brest", pop: 139000 },
    { name: "Rennes", pop: 220000 },
];
await client.query(
    "UNWIND $rows AS row " +
    "CREATE (:City {name: row.name, pop: row.pop})",
    { parameters: { rows } },
);

double(), exported by the package, sends a whole number as a Double. It matters where the type changes the result, such as division: RETURN $x / 4 is 2 for { x: 10 } and 2.5 for { x: double(10) }.

Any other value, such as undefined, a Date, a Map or a class instance, is refused before the query is sent, with a TuringQueryError of status PARAMETER_ERROR: Parameter $when is a Date, which a query parameter cannot hold. Send a date as an ISO 8601 string and convert it in the query:

await client.query("RETURN datetime($when) AS d", {
    parameters: { when: new Date().toISOString() },
});

Parameters count towards the 1 MiB limit of a request, together with the query text.

​

Versioning

Writes run inside a change:

const { chunks } = await client.query("CHANGE NEW");
client.setChange(chunks[0].columns[0].get(0));

await client.query("CREATE (:Person {name: 'Zoe'})");
await client.query("CHANGE SUBMIT");
client.setChange("main");

To read a past commit, load it with LOAD COMMIT and then pass its hash:

const [[commits]] = await client.queryData(
    "CALL db.history() YIELD `commit` RETURN `commit`",
);
// newest first: commits[0] is the latest one, marked (HEAD)
const previous = commits[1];

await client.query(`LOAD COMMIT '${previous}'`);
await client.queryData("MATCH (p:Person) RETURN count(p)", {
    commit: previous,
});

• Unlike the Python SDK’s checkout(), the client does not load a past commit for you. Without LOAD COMMIT, a query on a commit that is not in memory fails with COMMIT_NOT_LOADED. LOAD COMMIT on a loaded commit does nothing.
• db.history() marks the latest commit with a (HEAD) suffix. Strip it before passing that hash.
• setChange("main") and setCommit("head") return the client to the latest state of main. See Time travel for the versioning model.

​

Errors

A failed query rejects with a TuringQueryError, which carries a status and the server’s message:

import { TuringQueryError } from "turingdb";

try {
    await client.query("MATCH (n RETURN n");
} catch (e) {
    if (e instanceof TuringQueryError) {
        console.log(e.status);    // PARSE_ERROR
        // the query, a marker under the error,
        // and "syntax error, unexpected RETURN"
        console.log(e.message);
    }
}

A failure to reach the server rejects with the TypeError that fetch throws instead: fetch failed in Node.js when no server is listening, and Failed to fetch in a browser, which also covers a request blocked because the page is on another origin. A cancelled query rejects with an AbortError.

​

The wasm decoder

The client loads its decoder with new URL("turing_wasm_decoder.wasm", import.meta.url), the file next to it in the package. Node.js, browsers and bundlers that understand that pattern find it with no configuration. With Vite’s dev server, exclude the package from pre-bundling (optimizeDeps: { exclude: ["turingdb"] }, see In the browser).

To serve the file from somewhere else, such as a CDN, pass its address:

const client = new TuringClient({
    url: "/query",
    wasmUrl: "https://cdn.example.com/turing_wasm_decoder.wasm",
});

Serve the file as application/wasm, which most web servers already do.

​

Links

• The package on npm: npmjs.com/package/turingdb
• Its source, in the TuringDB repository: github.com/turing-db/turingdb/tree/main/wasm/npm