mumpixsl

Node.js SDK for MumpixSL (mumpixd).

Includes three protocol clients with matching operation coverage:

• MumpixSLClient (REST)
• MumpixSLWsClient (WebSocket)
• MumpixSLIpcClient (Unix socket IPC)

The Mumpix Family

• MumpixDB — Mumpix Database
• MumpixFS — Mumpix File System
• MumpixFE — Mumpix Frontend
• MumpixSL — Mumpix System Level

Install

npm install mumpixsl

Requirements

• Node.js >=18
• Running mumpixd

Default endpoints:

• REST: http://127.0.0.1:7770
• WS: ws://127.0.0.1:7771
• IPC: /run/mumpixd/mumpixd.sock (with legacy fallback /tmp/mumpixd.sock)

REST Client

import { MumpixSLClient } from "mumpixsl";

const m = new MumpixSLClient({ baseUrl: "http://127.0.0.1:7770" });

await m.setKey("memory^user^name", "Carrera");
const row = await m.getKey("memory^user^name");
console.log(row.value);

const listed = await m.scan("memory^", { limit: 50 });
console.log(listed.rows?.length ?? listed.length);

WebSocket Client

import { MumpixSLWsClient } from "mumpixsl";

const ws = new MumpixSLWsClient({ url: "ws://127.0.0.1:7771" });
await ws.connect();

const off = ws.onEvent((event) => {
  console.log(event.type, event.key);
});

const { watchId } = await ws.watch("memory^", { recursive: true });
await ws.set("memory^demo^counter", 1);
await ws.unwatch(watchId);

off();
await ws.close();

IPC Client

import { MumpixSLIpcClient } from "mumpixsl";

const ipc = new MumpixSLIpcClient({ socketPath: "/run/mumpixd/mumpixd.sock" });
await ipc.connect();

const stats = await ipc.stats();
console.log(stats.keys, stats.generation);

await ipc.close();

Operation Coverage

Shared data operations

• ping()
• stats()
• get(key, raw?) / getKey(key, { raw })
• set(key, value) / setKey(key, value)
• delete(key) / deleteKey(key)
• scan(prefix, { limit, cursor, resolveLinks, keysOnly })
• children(prefix) (WS/IPC)
• exists(key) (WS/IPC)
• resolve(key, { maxHops }) (WS/IPC)
• setLink(key, target) (WS/IPC)
• watch(prefix, { recursive, watchId }) (WS/IPC)
• unwatch(watchId) (WS/IPC)

File operations (REST)

• listFiles()
• importFile({ name, data, alias })
• exportFile(idOrAlias)

WS/IPC names:

• fsImport({ name, data, mime })
• fsExport(keyOrId)
• fsList(prefix?)

Sync operations

REST names:

• syncStatus()
• syncPeerConnect(peerId)
• syncPeerDisconnect(peerId)
• syncExportFull()
• syncPacket(peerId, packet)

WS/IPC names:

• syncHello(nodeId, sinceGeneration?)
• syncStatus()
• syncPeerConnected(peerId)
• syncPeerDisconnected(peerId)
• syncFullExport()
• syncReceivePacket(peerId, packet)
• syncDelta(sinceGeneration?, limit?)
• syncApply(entries)
• snapshotExport()
• snapshotImport(snapshot)

Error Model

• REST throws Error with status and response when available.
• WS/IPC throws protocol errors from server replies.
• Pending WS/IPC calls are rejected if transport closes.

try {
  await m.setKey("memory^x", 1);
} catch (err) {
  console.error(err.message, err.status, err.response);
}

Troubleshooting

• ECONNREFUSED: daemon not running or wrong endpoint.
• IPC ENOENT: socket path missing.
• No watch events: call watch(prefix) first, then mutate keys.
• Sync ops fail: daemon not started with sync enabled.

License

BUSL-1.1