wstp-node 0.3.0

package/examples/monitor_demo.js

@@ -0,0 +1,206 @@
+// =============================================================================
+// wstp-backend/monitor_demo.js
+//
+// Shows three approaches to monitoring a running Wolfram computation in real
+// time.  The computation under observation is:
+//
+//   Do[ i++; Pause[1], {i, 0, N-1} ]   – increments i each second
+//
+// ── WHY a parallel subsession can't directly spy on the main kernel ─────────
+//
+// A WSTP subsession is a completely independent WolframKernel process; it has
+// its own memory. You cannot query "i in kernel A" from "kernel B" — there is
+// no shared address space.
+//
+// Additionally, while the main kernel is busy inside a Do-loop, its WSTP link
+// is occupied: sending a second EvaluatePacket on the same link would be
+// ignored / corrupt the link.
+//
+// ── The three working patterns ───────────────────────────────────────────────
+//
+//  APPROACH 1  (JS-driven loop)
+//    Drive the loop from JS.  Each `session.evaluate('i++')` returns the new
+//    value of i to JS immediately.  JS controls the pacing and can read i
+//    between any two steps.  No extra kernel or link needed.
+//
+//  APPROACH 2  (side-channel link via LinkWrite)
+//    The kernel creates a named WSTP listener link, hands its name to JS, then
+//    runs the Do-loop.  Inside the loop it calls  LinkWrite[$mon, i]  after
+//    each step.  A WstpReader in JS receives every value the instant it is
+//    written — the two directions are fully independent:
+//      · main link  carries EvaluatePacket[Do[...]]  (busy, one-way)
+//      · monitor link carries integer values         (streaming, read-only)
+//    This is true real-time monitoring of a running kernel.
+//
+//  APPROACH 3  (shared temp file)
+//    Simplest, zero extra protocol: the loop writes i to /tmp/wstp_i.txt each
+//    tick; a Node.js setInterval reads the file every 500 ms.  Works well
+//    when you don't want to write any C++ addon code.
+// =============================================================================
+
+'use strict';
+
+const path = require('path');
+const fs   = require('fs');
+
+const { WstpSession, WstpReader } =
+    require(path.join(__dirname, '..', 'build', 'Release', 'wstp'));
+
+const sleep = ms => new Promise(r => setTimeout(r, ms));
+
+function section(title) {
+    console.log('\n' + '═'.repeat(62));
+    console.log('  ' + title);
+    console.log('═'.repeat(62));
+}
+
+// ── pretty-print a typed ExprTree (integers just shown as number) ─────────────
+function pp(node) {
+    if (!node) return String(node);
+    if (node.type === 'integer' || node.type === 'real') return String(node.value);
+    if (node.type === 'string')  return `"${node.value}"`;
+    if (node.type === 'symbol')  return node.value;
+    if (node.type === 'function')
+        return `${node.head}[${(node.args || []).map(pp).join(', ')}]`;
+    return JSON.stringify(node);
+}
+
+// =============================================================================
+async function main() {
+    const STEPS = 8;   // number of iterations (each sleeps 1 s in the kernel)
+
+    // =========================================================================
+    section('APPROACH 1 — JS-driven loop');
+    console.log(`
+  Instead of sending "Do[i++; Pause[1], {STEPS}]" as a single blocked call,
+  drive each step from JS.  After every evaluate() call you receive the
+  current value of i and can print, log, or react to it.
+`);
+    const s1 = new WstpSession();
+    await s1.evaluate('i = 0');
+
+    for (let step = 0; step < STEPS; step++) {
+        const result = await s1.evaluate('i++; i');   // increment and return
+        process.stdout.write(`  step ${step + 1}/${STEPS}  →  i = ${pp(result)}\n`);
+        // The 1 s pause is simulated here on the JS side; replace with
+        // your real inter-step work if needed.
+        await sleep(1000);
+    }
+    s1.close();
+    console.log('  Session closed.\n');
+
+
+    // =========================================================================
+    section('APPROACH 2 — side-channel link (WstpReader + LinkWrite)');
+    console.log(`
+  The kernel creates a TCPIP WSTP listener link.  A WstpReader in JS connects
+  to it.  The Do-loop writes i to the monitor link after each step; JS
+  receives every integer the moment it is written, while the main evaluation
+  is still running.
+`);
+    const s2 = new WstpSession();
+
+    // Step A: make the kernel create a listener link and tell us its name.
+    // $monLink is a LinkObject["port@host,port@host", id, n].
+    // [[1]] extracts the connection-name string directly.
+    console.log('  Creating monitor link inside kernel…');
+    await s2.evaluate('$monLink = LinkCreate[LinkProtocol -> "TCPIP"]');
+    const linkNameExpr = await s2.evaluate('$monLink[[1]]');
+    const linkName = linkNameExpr.value;
+    if (!linkName) throw new Error('Could not read link name: ' + JSON.stringify(linkNameExpr));
+    console.log(`  Monitor link name: ${linkName}`);
+
+    // Step B: connect from JS — constructor is now non-blocking.
+    // WSActivate (the WSTP handshake) is deferred to the thread pool
+    // inside the first readNext() call, so it runs concurrently with the loop.
+    const reader = new WstpReader(linkName, 'TCPIP');
+    console.log('  WstpReader opened (handshake deferred to first read).');
+
+    // Step C: start the Do-loop WITHOUT awaiting — it runs on the thread pool.
+    // The kernel enters the loop and calls LinkWrite after each Pause[1].
+    // This is what allows WSActivate (called inside readNext) to complete:
+    // the kernel's WSTP runtime processes the pending connection from the
+    // reader as soon as it starts calling LinkWrite.
+    const loopDone = s2.evaluate(
+        `Do[ i++; LinkWrite[$monLink, i]; Pause[1], {i, 0, ${STEPS - 1}} ]; ` +
+        'LinkClose[$monLink]; "loop-done"'
+    );
+
+    // Step D: read values as they stream in.
+    // The first readNext() also completes the WSActivate handshake on the
+    // thread pool — no blocking of the JS event loop at any point.
+    console.log('  Reading monitor stream:');
+    let received = 0;
+    while (received < STEPS) {
+        try {
+            const val = await reader.readNext();
+            process.stdout.write(`  monitor → i = ${pp(val)}\n`);
+            received++;
+        } catch (err) {
+            // Link was closed by the kernel (normal end).
+            console.log(`  Monitor link closed: ${err.message}`);
+            break;
+        }
+    }
+
+    // Step E: wait for the main evaluation to finish.
+    const loopResult = await loopDone;
+    console.log(`  Main eval result: ${pp(loopResult)}`);
+    reader.close();
+    s2.close();
+
+
+    // =========================================================================
+    section('APPROACH 3 — shared temp file (no addon changes needed)');
+    console.log(`
+  The loop writes i to /tmp/wstp_i.txt after each step.
+  A Node.js setInterval polls the file every 500 ms.
+  Simplest option — no extra WSTP infrastructure.
+`);
+    const POLL_FILE = '/tmp/wstp_monitor_i.txt';
+    const s3 = new WstpSession();
+
+    // Start the loop in background.
+    const loopDone3 = s3.evaluate(
+        `Do[ i++; Export["${POLL_FILE}", i, "Text"]; Pause[1], {i, 0, ${STEPS - 1}} ]; ` +
+        '"file-loop-done"'
+    );
+
+    // Poll from JS.
+    let lastSeen = null;
+    const poll = setInterval(() => {
+        try {
+            const txt = fs.readFileSync(POLL_FILE, 'utf8').trim();
+            if (txt !== lastSeen) {
+                lastSeen = txt;
+                process.stdout.write(`  poll → i = ${txt}\n`);
+            }
+        } catch (_) { /* file not written yet */ }
+    }, 500);
+
+    await loopDone3;
+    clearInterval(poll);
+    // Final read to catch the last value.
+    try {
+        process.stdout.write(`  final file value: ${fs.readFileSync(POLL_FILE, 'utf8').trim()}\n`);
+    } catch (_) {}
+    s3.close();
+
+
+    // =========================================================================
+    section('Summary');
+    console.log(`
+  ┌──────────────────────────┬────────────┬────────────┬───────────────────┐
+  │ Approach                 │ Real-time? │ New addon? │ Notes             │
+  ├──────────────────────────┼────────────┼────────────┼───────────────────┤
+  │ 1. JS-driven loop        │ yes        │ no         │ JS controls pace  │
+  │ 2. WstpReader side chan.  │ yes        │ WstpReader │ true streaming    │
+  │ 3. Temp file polling     │ ~500 ms    │ no         │ simplest setup    │
+  └──────────────────────────┴────────────┴────────────┴───────────────────┘
+`);
+}
+
+main().catch(err => {
+    console.error('\nFatal error:', err);
+    process.exitCode = 1;
+});

package/index.d.ts

@@ -0,0 +1,284 @@
+// wstp-backend — TypeScript declarations
+
+/**
+ * A Wolfram Language expression, converted from the WSTP wire format.
+ *
+ * Exactly one of the structural fields will be set depending on the
+ * expression type:
+ *   - integer: `type === "integer"`, `value` is a JS number
+ *   - real:    `type === "real"`,    `value` is a JS number
+ *   - string:  `type === "string"`,  `value` is a JS string
+ *   - symbol:  `type === "symbol"`,  `value` is the symbol name
+ *   - function:`type === "function"`, `head` is the head name, `args` is the argument list
+ *   - error:   `type === undefined`, `error` is a message string (never resolved normally)
+ */
+export interface WExpr {
+    type?:   "integer" | "real" | "string" | "symbol" | "function";
+    value?:  number | string;   // set for integer / real / string / symbol
+    head?:   string;            // set for function
+    args?:   WExpr[];           // set for function
+    error?:  string;            // set when addon encountered an internal error
+}
+
+/**
+ * Everything the kernel sends for one cell evaluation.
+ *
+ * The kernel sends packets in this order:
+ *   InputNamePacket  → cellIndex
+ *   (computation)
+ *   MessagePacket + TextPacket (0 or more pairs) → messages
+ *   TextPacket (0 or more)                       → print
+ *   OutputNamePacket                              → outputName
+ *   ReturnPacket                                  → result
+ */
+export interface EvalResult {
+    /** The n in In[n]:= — monotonically increasing counter for each evaluation. */
+    cellIndex:  number;
+    /** E.g. "Out[42]=" for a non-Null result, or "" when the result is Null. */
+    outputName: string;
+    /** The expression returned by the kernel (ReturnPacket payload). */
+    result:     WExpr;
+    /** Lines written via Print[] or other output functions, in order. */
+    print:      string[];
+    /**
+     * Kernel messages, one string per message.
+     * Format: "symbol::tag — human readable text"
+     * E.g. "Power::infy — Infinite expression 1/0 encountered."
+     */
+    messages:   string[];
+    /** True when the evaluation was stopped by abort(). */
+    aborted:    boolean;
+}
+
+/**
+ * Optional streaming callbacks for one evaluate() call.
+ *
+ * Both callbacks are invoked on the main thread as the kernel produces
+ * output — before the returned Promise resolves.  Use them for real-time
+ * progress feedback during long computations.
+ */
+export interface EvalOptions {
+    /** Called once per line written via Print[] (or similar output functions). */
+    onPrint?:   (line: string) => void;
+    /** Called once per kernel message (e.g. "Power::infy: Infinite expression…"). */
+    onMessage?: (msg:  string) => void;
+    /**
+     * Called when the kernel opens a Dialog[] subsession.
+     * @param level  Nesting depth (1 for the outermost dialog).
+     */
+    onDialogBegin?: (level: number) => void;
+    /**
+     * Called once per Print[] line produced inside the dialog subsession.
+     * @param line  Output line text.
+     */
+    onDialogPrint?: (line: string) => void;
+    /**
+     * Called when the dialog subsession closes (Return[] or kernel exit).
+     * @param level  The nesting depth that just closed.
+     */
+    onDialogEnd?: (level: number) => void;
+}
+
+/**
+ * A session wrapping one WolframKernel process connected over WSTP.
+ *
+ * Multiple evaluate() calls are automatically serialised through an
+ * internal queue — it is safe to fire them without awaiting.  The kernel
+ * link is never corrupted even under concurrent callers.
+ */
+export class WstpSession {
+    /**
+     * Launch a new WolframKernel process and connect to it over WSTP.
+     * @param kernelPath  Full path to WolframKernel binary.
+     *                    Defaults to the standard macOS install location.
+     * @throws if the kernel cannot be launched or the link fails to activate.
+     */
+    constructor(kernelPath?: string);
+
+    /**
+     * Evaluate a Wolfram Language expression string and return the full result.
+     *
+     * The kernel parses the string with ToExpression, evaluates it, and
+     * returns an EvalResult capturing the return value, all Print[] output,
+     * and all kernel messages that were emitted during evaluation.
+     *
+     * Multiple calls are serialised automatically — you may fire them
+     * concurrently without awaiting; each one will start after the previous
+     * one finishes.
+     *
+     * @param expr  Wolfram Language expression as a string.
+     * @param opts  Optional streaming callbacks (`onPrint`, `onMessage`).
+     * @returns     Promise that resolves with the EvalResult when the kernel responds.
+     */
+    evaluate(expr: string, opts?: EvalOptions): Promise<EvalResult>;
+
+    /**
+     * Exit the currently-open Dialog[] subsession.
+     *
+     * Sends `Return[retVal]` as `EnterTextPacket` — the interactive-context
+     * packet that the kernel recognises as "exit the dialog".  This is
+     * different from `dialogEval('Return[]')` which uses `EvaluatePacket`
+     * and leaves `Return[]` unevaluated (no enclosing Do/Block to return from).
+     *
+     * Resolves with `null` once `EndDialogPacket` is received.
+     * Rejects immediately if `isDialogOpen` is false.
+     *
+     * @param retVal  Optional Wolfram Language string to pass as the return
+     *                value of `Dialog[]`, e.g. `'42'` or `'myVar'`.
+     */
+    exitDialog(retVal?: string): Promise<null>;
+
+    /**
+     * Evaluate an expression inside the currently-open Dialog[] subsession.
+     *
+     * Queues `expr` for evaluation by the kernel's dialog REPL.  Resolves with
+     * the WExpr result once the dialog loop has processed it.  Rejects if
+     * `isDialogOpen` is false at call time (i.e. no dialog is currently open).
+     *
+     * @param expr  Wolfram Language expression string.
+     * @returns     Promise that resolves with the WExpr result.
+     */
+    dialogEval(expr: string): Promise<WExpr>;
+
+    /**
+     * Send WSInterruptMessage to the kernel (best-effort).
+     *
+     * Whether this has any effect depends on whether a Wolfram-side interrupt
+     * handler has been installed, e.g.:
+     * ```
+     * Internal`AddHandler["Interrupt", Function[Null, Dialog[]]]
+     * ```
+     * Without such a handler this is a no-op.  For a guaranteed way to enter
+     * a dialog, call `Dialog[]` directly from Wolfram code.
+     *
+     * @returns true if the message was posted to the link successfully.
+     */
+    interrupt(): boolean;
+
+    /** True while a Dialog[] subsession is open on this link. */
+    readonly isDialogOpen: boolean;
+
+    /**
+     * Interrupt the currently running evaluate() call.
+     *
+     * Posts WSAbortMessage to the kernel.  The kernel stops its current
+     * computation and the evaluate() Promise resolves with `aborted: true`
+     * and `result: { type: "symbol", value: "$Aborted" }`.
+     *
+     * The kernel remains alive and can accept further evaluations.
+     *
+     * @returns true if the abort message was posted successfully.
+     */
+    abort(): boolean;
+
+    /**
+     * Evaluate an expression, returning just the result expression
+     * (not a full EvalResult).
+     *
+     * `sub()` is always prioritised over pending `evaluate()` calls: it runs
+     * before any already-queued evaluations.  If the session is currently busy,
+     * `sub()` waits for the in-flight evaluation to finish, then runs next
+     * (ahead of any other queued `evaluate()` calls).  If idle, it starts
+     * immediately.
+     *
+     * Multiple `sub()` calls are queued FIFO among themselves and all run
+     * before the next `evaluate()` call in the queue.
+     *
+     * @param expr  Wolfram Language expression string to evaluate.
+     * @returns     Promise that resolves with the WExpr result.
+     */
+    sub(expr: string): Promise<WExpr>;
+
+    /**
+     * Launch an independent child kernel as a new WstpSession.
+     *
+     * The child has completely isolated state (variables, definitions, memory).
+     * It must be closed independently with child.close().
+     *
+     * @param kernelPath  Optional path override; defaults to the parent's path.
+     */
+    createSubsession(kernelPath?: string): WstpSession;
+
+    /**
+     * Send Quit[] to the kernel, close the link, and release all resources.
+     * Subsequent calls to evaluate() will reject immediately.
+     */
+    close(): void;
+
+    /** True while the link is open and the kernel is running. */
+    readonly isOpen: boolean;
+}
+
+/**
+ * A reader that connects to a named WSTP link created by the kernel
+ * (via `LinkCreate`) and receives expressions pushed by the kernel
+ * (via `LinkWrite`).
+ *
+ * Use this for real-time monitoring: the kernel pushes variable snapshots
+ * while the main link is blocked on a long evaluation.
+ *
+ * @example
+ * // Wolfram side:
+ * //   $mon = LinkCreate[LinkProtocol -> "TCPIP"];
+ * //   linkName = $mon[[1]];          (* extract string from LinkObject *)
+ * //   Do[LinkWrite[$mon, i]; Pause[1], {i, 1, 10}];
+ * //   LinkClose[$mon];
+ *
+ * // JS side:
+ * const reader = new WstpReader(linkName);
+ * while (reader.isOpen) {
+ *     try {
+ *         const v = await reader.readNext();
+ *         console.log('monitor:', v);
+ *     } catch { break; }
+ * }
+ */
+export class WstpReader {
+    /**
+     * Connect to a named WSTP link that is already listening.
+     *
+     * @param linkName  The name returned by Wolfram's `$link[[1]]` or `LinkName[$link]`.
+     *                  For TCPIP links this looks like "port@host,0@host".
+     * @param protocol  Link protocol, default "TCPIP".
+     * @throws if the connection cannot be established.
+     */
+    constructor(linkName: string, protocol?: string);
+
+    /**
+     * Wait for the next expression written by the kernel via LinkWrite.
+     *
+     * Blocks on Node's thread pool until an expression arrives.
+     * When the kernel closes the link (LinkClose[$link]), this rejects.
+     *
+     * @returns Promise that resolves with the next WExpr.
+     */
+    readNext(): Promise<WExpr>;
+
+    /** Close the link and release resources. */
+    close(): void;
+
+    /** True while the link is open. */
+    readonly isOpen: boolean;
+}
+
+/**
+ * Register a callback that receives internal C++ diagnostic messages.
+ *
+ * Messages include WSTP packet traces (`[Eval] pkt=N`), TSFN dispatch
+ * timestamps (`[TSFN][onPrint] dispatch +Nms`), `WstpReader` spin-wait
+ * traces, and kernel lifecycle events (`[WarmUp]`, `[Session]`).
+ *
+ * The callback fires on the JS main thread, so it can safely write to
+ * `process.stderr` or update UI.  It does **not** prevent the Node.js
+ * process from exiting normally.
+ *
+ * Alternatively, set `DEBUG_WSTP=1` in the environment to write the same
+ * messages directly to `stderr` from C++ (no JS handler needed):
+ * ```
+ * DEBUG_WSTP=1 node myscript.js 2>diag.txt
+ * ```
+ *
+ * @param fn  Callback receiving each diagnostic message string,
+ *            or `null` / `undefined` to clear a previously-set handler.
+ */
+export function setDiagHandler(fn: ((msg: string) => void) | null | undefined): void;

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "wstp-node",
+  "version": "0.3.0",
+  "description": "Native Node.js addon for Wolfram/Mathematica WSTP — kernel sessions with evaluation queue, streaming Print/messages, Dialog subsessions, and side-channel WstpReader",
+  "main": "build/Release/wstp.node",
+  "types": "index.d.ts",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vanbaalon/mathematica-wstp-node.git"
+  },
+  "keywords": [
+    "wolfram",
+    "mathematica",
+    "wstp",
+    "native-addon",
+    "kernel",
+    "wolframscript"
+  ],
+  "author": "vanbaalon",
+  "license": "MIT",
+  "os": [
+    "darwin",
+    "linux"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "src/addon.cc",
+    "build.sh",
+    "binding.gyp",
+    "index.d.ts",
+    "examples/",
+    "test.js",
+    "test_interrupt_dialog.js"
+  ],
+  "scripts": {
+    "install": "bash build.sh",
+    "build": "bash build.sh",
+    "build:debug": "bash build.sh debug",
+    "clean": "bash build.sh clean",
+    "test": "node test.js",
+    "demo": "node examples/demo.js"
+  },
+  "dependencies": {
+    "node-addon-api": "^8.0.0"
+  },
+  "devDependencies": {
+    "node-gyp": "^10.0.0"
+  }
+}