TypeScript client

mushroomdb-client is a typed wrapper over the HTTP API and its WebSocket stream. It talks to a running mushroomdb serve; it does not embed the engine.

npm install mushroomdb-client

It needs Node 18 or later, and runs in a browser. In a Node without a global WebSocket, install ws as well if you use subscriptions.

Quick start

import { MushroomClient } from 'mushroomdb-client';

const client = new MushroomClient('http://127.0.0.1:8080', { token: 'your-token' });

// A read.
const result = await client.query(
  'MATCH (p:Person) RETURN p.id AS id, p.name AS name LIMIT 10',
);
console.log(result.columns); // ['id', 'name']
console.log(result.rows);    // [['person-01', 'Alice'], ...]

// A read with a parameter.
const one = await client.query(
  'MATCH (p:Person {id: $pid}) RETURN p.name AS name',
  { params: { pid: 'person-01' } },
);

// Why are these two linked?
const why = await client.explain('person-01', 'proj-01');

The token is sent as an Authorization: Bearer header, and on the WebSocket URL as ?token= for subscriptions. Leave the second argument out for a server started without one.

Methods

Each method calls one route. The route’s page has the request and the response in full.

What it does not wrap

All HTTP routes and WebSocket endpoints have a method on the client.

Creating a node, setting a property and deleting can also be done through client.query, with a Cypher CREATE, SET or DELETE.

Query options

client.query(cypher, opts?) accepts three optional fields beyond params:

Errors

A response that is not a success throws MushroomError. Its detail, which is also its message, is what the server said went wrong. Empty or plain-text error bodies (e.g. 404 with no JSON, or 413) surface as MushroomError("HTTP <status>") rather than a raw parse error.

import { MushroomError } from 'mushroomdb-client';

try {
  await client.query('BAD CYPHER');
} catch (err) {
  if (err instanceof MushroomError) {
    console.error('Query failed:', err.detail);
  }
}

Subscriptions

const handle = await client.subscribe(
  { rules: ['skill_fit'], writes: true },
  (ev) => {
    switch (ev.type) {
      case 'edge_fired':
        console.log(`${ev.rule}: ${ev.src_key} -> ${ev.dst_key} (commit ${ev.commit_seq})`);
        break;
      case 'lagged':
        console.warn(`missed ${ev.missed} events; re-read what you depend on`);
        break;
    }
  },
);

// Later:
await handle.close();

• A subscription sees only writes made through the server it is connected to.
• It does not reconnect. When the connection drops, no more events arrive; subscribe again.
• A lagged event means the server’s queue for this subscriber overflowed and some events were not sent. The stream goes on.
• In a Node without a global WebSocket, pass the ws constructor as wsConstructor in the first argument.

Every option of every method is in the package’s own README.