@eplightning/nats-server-client 0.1.0

package/README.md

@@ -0,0 +1 @@
+# @eplightning/nats-server-client

package/dist/index.cjs

@@ -0,0 +1,230 @@
+var import_node_module = require("node:module");
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+function __accessProp(key) {
+  return this[key];
+}
+var __toCommonJS = (from) => {
+  var entry = (__moduleCache ??= new WeakMap).get(from), desc;
+  if (entry)
+    return entry;
+  entry = __defProp({}, "__esModule", { value: true });
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (var key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(entry, key))
+        __defProp(entry, key, {
+          get: __accessProp.bind(from, key),
+          enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+        });
+  }
+  __moduleCache.set(from, entry);
+  return entry;
+};
+var __moduleCache;
+var __returnValue = (v) => v;
+function __exportSetter(name, newValue) {
+  this[name] = __returnValue.bind(null, newValue);
+}
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: __exportSetter.bind(all, name)
+    });
+};
+
+// src/index.ts
+var exports_src = {};
+__export(exports_src, {
+  RANDOM_PORT: () => RANDOM_PORT,
+  NatsServer: () => NatsServer
+});
+module.exports = __toCommonJS(exports_src);
+
+// src/options.ts
+var RANDOM_PORT = -1;
+function buildArgs(opts) {
+  const args = [];
+  if (opts.port !== undefined) {
+    args.push("--port", String(opts.port));
+  }
+  if (opts.host !== undefined) {
+    args.push("--addr", opts.host);
+  }
+  if (opts.jetstream) {
+    args.push("--jetstream");
+    if (opts.storeDirectory !== undefined) {
+      args.push("--store_dir", opts.storeDirectory);
+    }
+  }
+  if (opts.username !== undefined) {
+    args.push("--user", opts.username);
+  }
+  if (opts.password !== undefined) {
+    args.push("--pass", opts.password);
+  }
+  if (opts.auth !== undefined) {
+    args.push("--auth", opts.auth);
+  }
+  if (opts.extraArguments !== undefined) {
+    args.push(...opts.extraArguments);
+  }
+  return args;
+}
+// src/server.ts
+var import_promises = require("node:fs/promises");
+var import_node_os = require("node:os");
+var import_node_path = require("node:path");
+var import_nats_server = require("@eplightning/nats-server");
+
+// src/process.ts
+var import_node_child_process = require("node:child_process");
+function spawnProcess(binaryPath, options) {
+  const child = import_node_child_process.spawn(binaryPath, options.args, {
+    stdio: ["ignore", "ignore", "pipe"]
+  });
+  let exitResolve;
+  const exitPromise = new Promise((resolve) => {
+    exitResolve = resolve;
+  });
+  child.stderr.setEncoding("utf8");
+  const stderrBuffer = { value: "" };
+  child.stderr.on("data", (chunk) => {
+    stderrBuffer.value = stderrBuffer.value.concat(chunk);
+    const lines = stderrBuffer.value.split(/\r?\n/);
+    stderrBuffer.value = lines.pop() ?? "";
+    for (const line of lines) {
+      options.onStderr(line);
+    }
+  });
+  child.on("exit", (code) => {
+    if (stderrBuffer.value !== "") {
+      options.onStderr(stderrBuffer.value);
+    }
+    options.onExit(code);
+    exitResolve(code);
+  });
+  return {
+    kill(signal) {
+      child.kill(signal);
+    },
+    waitForExit() {
+      return exitPromise;
+    }
+  };
+}
+
+// src/server.ts
+var CLIENT_LISTEN_RE = /Listening for client connections on .+:(\d+)$/;
+var SERVER_READY_RE = /Server is ready$/;
+
+class NatsServer {
+  host;
+  port;
+  url;
+  _process;
+  _stopped = false;
+  constructor(process, port, host) {
+    this._process = process;
+    this.port = port;
+    this.host = host;
+    this.url = `nats://${host === "0.0.0.0" ? "127.0.0.1" : host}:${port}`;
+  }
+  static async start(options = {}) {
+    const opts = {
+      host: "127.0.0.1",
+      startupTimeoutMillis: 20000,
+      storeDirectory: import_node_path.join(import_node_os.tmpdir(), `nats-${crypto.randomUUID()}`),
+      removeStoreDirectoryOnExit: options.storeDirectory == null,
+      ...options
+    };
+    const host = opts.host ?? "0.0.0.0";
+    const isRandomPort = opts.port === RANDOM_PORT;
+    const binaryPath = opts.binaryPath ?? await import_nats_server.getBinaryPath();
+    const args = buildArgs(opts);
+    if (opts.jetstream && opts.storeDirectory) {
+      await import_promises.mkdir(opts.storeDirectory, { recursive: true });
+    }
+    return new Promise((resolve, reject) => {
+      let resolved = false;
+      let assignedPort = isRandomPort ? undefined : opts.port ?? 4222;
+      let serverReady = false;
+      let proc;
+      const timeoutTimer = setTimeout(() => {
+        if (!resolved) {
+          resolved = true;
+          try {
+            proc.kill("SIGKILL");
+          } catch {}
+          reject(new Error(`NATS server did not become ready within ${opts.startupTimeoutMillis}ms.`));
+        }
+      }, opts.startupTimeoutMillis);
+      function tryResolve() {
+        if (resolved || assignedPort == null || !serverReady)
+          return;
+        resolved = true;
+        clearTimeout(timeoutTimer);
+        resolve(new NatsServer(proc, assignedPort, host));
+      }
+      function handleLine(line) {
+        if (isRandomPort && assignedPort == null) {
+          const match = CLIENT_LISTEN_RE.exec(line);
+          if (match) {
+            assignedPort = parseInt(match[1], 10);
+          }
+        }
+        if (!serverReady && SERVER_READY_RE.test(line)) {
+          serverReady = true;
+        }
+        tryResolve();
+      }
+      try {
+        proc = spawnProcess(binaryPath, {
+          args,
+          onStderr: handleLine,
+          onExit: async (code) => {
+            if (!resolved) {
+              resolved = true;
+              clearTimeout(timeoutTimer);
+              reject(new Error(`NATS server exited unexpectedly with code ${code} before becoming ready.`));
+            } else {
+              if (opts.removeStoreDirectoryOnExit && opts.storeDirectory && opts.storeDirectory !== "/") {
+                try {
+                  await import_promises.rm(opts.storeDirectory, {
+                    recursive: true,
+                    force: true
+                  });
+                } catch (_error) {}
+              }
+            }
+          }
+        });
+      } catch (err) {
+        resolved = true;
+        clearTimeout(timeoutTimer);
+        const msg = err instanceof Error ? err.message : String(err);
+        reject(new Error(`Failed to start NATS server: ${msg}`));
+      }
+    });
+  }
+  static async startOnRandomPort(options = {}) {
+    return NatsServer.start({ ...options, port: RANDOM_PORT });
+  }
+  async stop(kill = false) {
+    if (this._stopped)
+      return;
+    this._stopped = true;
+    this._process.kill(kill ? "SIGKILL" : "SIGTERM");
+    await this._process.waitForExit();
+  }
+  waitForExit() {
+    return this._process.waitForExit();
+  }
+  get stopped() {
+    return this._stopped;
+  }
+}

package/dist/index.d.cts

@@ -0,0 +1,107 @@
+declare const RANDOM_PORT = -1;
+/**
+* NATS server options.
+*/
+interface NatsServerOptions {
+	/**
+	* Path to the nats-server binary.
+	*
+	* If omitted, resolved automatically from the `@eplightning/nats-server` package.
+	*/
+	binaryPath?: string;
+	/**
+	* Port to listen on for client connections.
+	*
+	* Use -1 to let the OS choose a random available port.
+	* Defaults to 4222 if not specified.
+	*/
+	port?: number;
+	/**
+	* Host to listen on. Defaults to "127.0.0.1".
+	*/
+	host?: string;
+	/**
+	* Enable JetStream.
+	*/
+	jetstream?: boolean;
+	/**
+	* Directory for JetStream storage.
+	*
+	* Defaults to random temporary directory.
+	*/
+	storeDirectory?: string;
+	/**
+	* Whether to remove store directory on stop.
+	*
+	* Defaults to true if using random temporary directory, false otherwise.
+	*/
+	removeStoreDirectoryOnExit?: boolean;
+	/**
+	* Maximum time in milliseconds to wait for the server to become ready.
+	*
+	* Defaults to 20000 (20 seconds).
+	*/
+	startupTimeoutMillis?: number;
+	/**
+	* User for authentication.
+	*/
+	username?: string;
+	/**
+	* Password for authentication.
+	*/
+	password?: string;
+	/**
+	* Authentication token.
+	*/
+	auth?: string;
+	/**
+	* Extra arguments to be passed.
+	*/
+	extraArguments?: string[];
+}
+/**
+* Represents a running NATS server process.
+*/
+declare class NatsServer {
+	/**
+	* The host the server is bound to.
+	*/
+	readonly host: string;
+	/**
+	* The port the server is listening on.
+	*/
+	readonly port: number;
+	/**
+	* The client URL for connecting (e.g. "nats://127.0.0.1:4222")
+	*/
+	readonly url: string;
+	private readonly _process;
+	private _stopped;
+	private constructor();
+	/**
+	* Starts a NATS server process with the given options.
+	*
+	* @param options
+	* @returns A `NatsServer` instance, ready to accept connections.
+	*/
+	static start(options?: NatsServerOptions): Promise<NatsServer>;
+	/**
+	* Starts a server on a random port.
+	*
+	* Equivalent to `NatsServer.start({ ...options, port: RANDOM_PORT })`.
+	*/
+	static startOnRandomPort(options?: Omit<NatsServerOptions, "port">): Promise<NatsServer>;
+	/**
+	* Sends SIGTERM to the server and waits for the process to exit.
+	*/
+	stop(kill?: boolean): Promise<void>;
+	/**
+	* Waits for the server process to exit.
+	*/
+	waitForExit(): Promise<number | null>;
+	/**
+	* Whether the server has been stopped.
+	*/
+	get stopped(): boolean;
+}
+export { RANDOM_PORT, NatsServerOptions, NatsServer };

package/dist/index.d.ts

@@ -0,0 +1,107 @@
+declare const RANDOM_PORT = -1;
+/**
+* NATS server options.
+*/
+interface NatsServerOptions {
+	/**
+	* Path to the nats-server binary.
+	*
+	* If omitted, resolved automatically from the `@eplightning/nats-server` package.
+	*/
+	binaryPath?: string;
+	/**
+	* Port to listen on for client connections.
+	*
+	* Use -1 to let the OS choose a random available port.
+	* Defaults to 4222 if not specified.
+	*/
+	port?: number;
+	/**
+	* Host to listen on. Defaults to "127.0.0.1".
+	*/
+	host?: string;
+	/**
+	* Enable JetStream.
+	*/
+	jetstream?: boolean;
+	/**
+	* Directory for JetStream storage.
+	*
+	* Defaults to random temporary directory.
+	*/
+	storeDirectory?: string;
+	/**
+	* Whether to remove store directory on stop.
+	*
+	* Defaults to true if using random temporary directory, false otherwise.
+	*/
+	removeStoreDirectoryOnExit?: boolean;
+	/**
+	* Maximum time in milliseconds to wait for the server to become ready.
+	*
+	* Defaults to 20000 (20 seconds).
+	*/
+	startupTimeoutMillis?: number;
+	/**
+	* User for authentication.
+	*/
+	username?: string;
+	/**
+	* Password for authentication.
+	*/
+	password?: string;
+	/**
+	* Authentication token.
+	*/
+	auth?: string;
+	/**
+	* Extra arguments to be passed.
+	*/
+	extraArguments?: string[];
+}
+/**
+* Represents a running NATS server process.
+*/
+declare class NatsServer {
+	/**
+	* The host the server is bound to.
+	*/
+	readonly host: string;
+	/**
+	* The port the server is listening on.
+	*/
+	readonly port: number;
+	/**
+	* The client URL for connecting (e.g. "nats://127.0.0.1:4222")
+	*/
+	readonly url: string;
+	private readonly _process;
+	private _stopped;
+	private constructor();
+	/**
+	* Starts a NATS server process with the given options.
+	*
+	* @param options
+	* @returns A `NatsServer` instance, ready to accept connections.
+	*/
+	static start(options?: NatsServerOptions): Promise<NatsServer>;
+	/**
+	* Starts a server on a random port.
+	*
+	* Equivalent to `NatsServer.start({ ...options, port: RANDOM_PORT })`.
+	*/
+	static startOnRandomPort(options?: Omit<NatsServerOptions, "port">): Promise<NatsServer>;
+	/**
+	* Sends SIGTERM to the server and waits for the process to exit.
+	*/
+	stop(kill?: boolean): Promise<void>;
+	/**
+	* Waits for the server process to exit.
+	*/
+	waitForExit(): Promise<number | null>;
+	/**
+	* Whether the server has been stopped.
+	*/
+	get stopped(): boolean;
+}
+export { RANDOM_PORT, NatsServerOptions, NatsServer };

package/dist/index.js

@@ -0,0 +1,187 @@
+// src/options.ts
+var RANDOM_PORT = -1;
+function buildArgs(opts) {
+  const args = [];
+  if (opts.port !== undefined) {
+    args.push("--port", String(opts.port));
+  }
+  if (opts.host !== undefined) {
+    args.push("--addr", opts.host);
+  }
+  if (opts.jetstream) {
+    args.push("--jetstream");
+    if (opts.storeDirectory !== undefined) {
+      args.push("--store_dir", opts.storeDirectory);
+    }
+  }
+  if (opts.username !== undefined) {
+    args.push("--user", opts.username);
+  }
+  if (opts.password !== undefined) {
+    args.push("--pass", opts.password);
+  }
+  if (opts.auth !== undefined) {
+    args.push("--auth", opts.auth);
+  }
+  if (opts.extraArguments !== undefined) {
+    args.push(...opts.extraArguments);
+  }
+  return args;
+}
+// src/server.ts
+import { mkdir, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { getBinaryPath } from "@eplightning/nats-server";
+
+// src/process.ts
+import { spawn } from "node:child_process";
+function spawnProcess(binaryPath, options) {
+  const child = spawn(binaryPath, options.args, {
+    stdio: ["ignore", "ignore", "pipe"]
+  });
+  let exitResolve;
+  const exitPromise = new Promise((resolve) => {
+    exitResolve = resolve;
+  });
+  child.stderr.setEncoding("utf8");
+  const stderrBuffer = { value: "" };
+  child.stderr.on("data", (chunk) => {
+    stderrBuffer.value = stderrBuffer.value.concat(chunk);
+    const lines = stderrBuffer.value.split(/\r?\n/);
+    stderrBuffer.value = lines.pop() ?? "";
+    for (const line of lines) {
+      options.onStderr(line);
+    }
+  });
+  child.on("exit", (code) => {
+    if (stderrBuffer.value !== "") {
+      options.onStderr(stderrBuffer.value);
+    }
+    options.onExit(code);
+    exitResolve(code);
+  });
+  return {
+    kill(signal) {
+      child.kill(signal);
+    },
+    waitForExit() {
+      return exitPromise;
+    }
+  };
+}
+
+// src/server.ts
+var CLIENT_LISTEN_RE = /Listening for client connections on .+:(\d+)$/;
+var SERVER_READY_RE = /Server is ready$/;
+
+class NatsServer {
+  host;
+  port;
+  url;
+  _process;
+  _stopped = false;
+  constructor(process, port, host) {
+    this._process = process;
+    this.port = port;
+    this.host = host;
+    this.url = `nats://${host === "0.0.0.0" ? "127.0.0.1" : host}:${port}`;
+  }
+  static async start(options = {}) {
+    const opts = {
+      host: "127.0.0.1",
+      startupTimeoutMillis: 20000,
+      storeDirectory: join(tmpdir(), `nats-${crypto.randomUUID()}`),
+      removeStoreDirectoryOnExit: options.storeDirectory == null,
+      ...options
+    };
+    const host = opts.host ?? "0.0.0.0";
+    const isRandomPort = opts.port === RANDOM_PORT;
+    const binaryPath = opts.binaryPath ?? await getBinaryPath();
+    const args = buildArgs(opts);
+    if (opts.jetstream && opts.storeDirectory) {
+      await mkdir(opts.storeDirectory, { recursive: true });
+    }
+    return new Promise((resolve, reject) => {
+      let resolved = false;
+      let assignedPort = isRandomPort ? undefined : opts.port ?? 4222;
+      let serverReady = false;
+      let proc;
+      const timeoutTimer = setTimeout(() => {
+        if (!resolved) {
+          resolved = true;
+          try {
+            proc.kill("SIGKILL");
+          } catch {}
+          reject(new Error(`NATS server did not become ready within ${opts.startupTimeoutMillis}ms.`));
+        }
+      }, opts.startupTimeoutMillis);
+      function tryResolve() {
+        if (resolved || assignedPort == null || !serverReady)
+          return;
+        resolved = true;
+        clearTimeout(timeoutTimer);
+        resolve(new NatsServer(proc, assignedPort, host));
+      }
+      function handleLine(line) {
+        if (isRandomPort && assignedPort == null) {
+          const match = CLIENT_LISTEN_RE.exec(line);
+          if (match) {
+            assignedPort = parseInt(match[1], 10);
+          }
+        }
+        if (!serverReady && SERVER_READY_RE.test(line)) {
+          serverReady = true;
+        }
+        tryResolve();
+      }
+      try {
+        proc = spawnProcess(binaryPath, {
+          args,
+          onStderr: handleLine,
+          onExit: async (code) => {
+            if (!resolved) {
+              resolved = true;
+              clearTimeout(timeoutTimer);
+              reject(new Error(`NATS server exited unexpectedly with code ${code} before becoming ready.`));
+            } else {
+              if (opts.removeStoreDirectoryOnExit && opts.storeDirectory && opts.storeDirectory !== "/") {
+                try {
+                  await rm(opts.storeDirectory, {
+                    recursive: true,
+                    force: true
+                  });
+                } catch (_error) {}
+              }
+            }
+          }
+        });
+      } catch (err) {
+        resolved = true;
+        clearTimeout(timeoutTimer);
+        const msg = err instanceof Error ? err.message : String(err);
+        reject(new Error(`Failed to start NATS server: ${msg}`));
+      }
+    });
+  }
+  static async startOnRandomPort(options = {}) {
+    return NatsServer.start({ ...options, port: RANDOM_PORT });
+  }
+  async stop(kill = false) {
+    if (this._stopped)
+      return;
+    this._stopped = true;
+    this._process.kill(kill ? "SIGKILL" : "SIGTERM");
+    await this._process.waitForExit();
+  }
+  waitForExit() {
+    return this._process.waitForExit();
+  }
+  get stopped() {
+    return this._stopped;
+  }
+}
+export {
+  RANDOM_PORT,
+  NatsServer
+};

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@eplightning/nats-server-client",
+  "version": "0.1.0",
+  "description": "Easy way of running NATS server for Bun, Node and Deno",
+  "type": "module",
+  "module": "./dist/index.js",
+  "main": "./dist/index.cjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist/",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "bunup --format esm,cjs",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@eplightning/nats-server": "*"
+  },
+  "devDependencies": {
+    "@nats-io/jetstream": "^3.3.1",
+    "@nats-io/transport-node": "^3.3.1"
+  },
+  "license": "Apache-2.0",
+  "keywords": [
+    "nats",
+    "nats-server",
+    "testing",
+    "binary"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/eplightning/nats-server-npm",
+    "directory": "packages/nats-server"
+  },
+  "engines": {
+    "bun": ">=1",
+    "node": ">=22",
+    "deno": ">=2"
+  }
+}