node.md

Node.js

Use the Meldbase client in Node.js when another server process needs to work with a running Meldbase service. Node connects over HTTP and WebSocket; it does not open a .meld file directly.

The @meldbase/client SDK is available on npm under the beta tag. See SDK compatibility and release status before upgrading.

Start a local service

From a Meldbase checkout, start an explicitly local development server:

go run ./cmd/meld serve --db /tmp/meldbase-node.meld --addr 127.0.0.1:8080 --dev-no-auth

--dev-no-auth is for local development only. Do not expose that server to a network.

Create a client

Node.js 20 or later is required. In another terminal, in your application directory:

npm install @meldbase/client@beta ws

Save this as node-tour.mjs in your application directory:

import WebSocket from "ws";
import { MeldbaseClient } from "@meldbase/client";

const client = new MeldbaseClient({
  baseUrl: "http://127.0.0.1:8080",
  webSocketFactory: (url) => new WebSocket(url),
});
const todos = client.collection("todos");
try {
  await todos.insertOne({ title: "Process a job", done: false });
  console.log(await todos.find({ done: false }).fetch());
} finally {
  client.close();
}

node node-tour.mjs

You should see an array containing your new todo and its _id. Run it again and the collection grows. The excerpts below assume an open client and its todos collection, as above.

For an authenticated service, supply a token issued by your identity system:

const client = new MeldbaseClient({
  baseUrl: process.env.MELDBASE_URL,
  accessToken: () => process.env.MELDBASE_ACCESS_TOKEN,
  webSocketFactory: (url) => new WebSocket(url),
});

Read and write documents

const todo = await todos.insertOne({
  title: "Process a job",
  done: false,
});

await todos.updateOne({ _id: todo._id }, { $set: { done: true } });

const completed = await todos.find({ done: true }).fetch();
console.log(completed);

Queries and updates are data, not JavaScript expressions. The server validates them and applies its own collection policy.

Subscribe to changes

const stop = todos.find({ done: false }).subscribe(
  (documents) => {
    queueWork(documents);
  },
  {
    onStatus(status) {
      logger.info({ state: status.state }, "meldbase connection");
    },
  },
);

process.once("SIGTERM", () => {
  stop();
  client.close();
});

The client reconnects subscriptions after a temporary connection loss. Treat stale and resyncing as connection state, not as permission to retry a write without first reconciling its outcome.

What comes next

Use the Browser guide for client-side applications. Use the Go tour when the current Go process should own the database file.