wstp-node 0.6.6 → 0.7.0

package/README.md

@@ -1,43 +1,60 @@
-# wstp-backend — API Reference
+# wstp-backend
 
 **Author:** Nikolay Gromov
 
-Native Node.js addon for Wolfram kernel communication over WSTP — supports full
-notebook-style evaluation with automatic `In`/`Out` history, real-time streaming,
-and an internal evaluation queue.  All blocking I/O runs on the libuv thread pool;
-the JS event loop is never stalled.
+Native Node.js addon for Wolfram kernel communication over WSTP. Enables notebook-style evaluation, real-time streaming, and robust kernel management from JavaScript.
+
+## Purpose
+
+This package lets you control a WolframKernel process from Node.js, supporting both batch and interactive notebook-style evaluation. It is ideal for building VS Code extensions, automating Mathematica workflows, and integrating Wolfram computation into JS apps.
+
+## Installation
+
+### Prerequisites
+
+| Requirement | Notes |
+|-------------|-------|
+| macOS | Tested on macOS 13+ (ARM64 and x86-64) |
+| Windows 10/11 x64 | See [InstallationWindows.md](InstallationWindows.md) for the full Windows guide |
+| Linux x86-64 / ARM64 | Should work with standard `node-gyp` toolchain |
+| Node.js ≥ 18 | Earlier versions may work but are untested |
+| Clang / Xcode Command Line Tools (macOS) | `xcode-select --install` |
+| MSVC Build Tools with C++ workload (Windows) | Visual Studio 2019+ or Build Tools |
+| Wolfram Mathematica or Wolfram Engine | Provides `WolframKernel` and the WSTP SDK headers/libraries |
+
+### 1. Clone
+
+```bash
+git clone https://github.com/vanbaalon/mathematica-wstp-node.git
+cd mathematica-wstp-node
+```
+
+### 2. Install Node dependencies
+
+```bash
+npm install
+```
+
+### 3. Build the native addon
+
+```bash
+bash build.sh
+```
+
+## Quick Start
 
 ```js
-const { WstpSession, WstpReader, setDiagHandler } = require('./build/Release/wstp.node');
+const { WstpSession } = require('./build/Release/wstp.node');
+const session = new WstpSession();
+session.evaluate('Prime[10]').then(r => {
+  console.log(r.result.value); // 29
+  session.close();
+});
 ```
 
----
+## API Reference
 
-## Table of Contents
-
-1. [Installation](#installation)
-2. [Batch mode vs interactive mode](#batch-mode-vs-interactive-mode)
-3. [Return types — `WExpr` and `EvalResult`](#return-types)
-4. [`WstpSession` — main evaluation session](#wstpsession)
-   - [Constructor](#constructor) — launch a kernel and open a session
-   - [`evaluate(expr, opts?)`](#evaluateexpr-opts) — queue an expression for evaluation; supports streaming `Print` callbacks
-   - [`sub(expr)`](#subexpr) — priority evaluation that jumps ahead of the queue, for quick queries during a long computation
-   - [`abort()`](#abort) — interrupt the currently running evaluation
-   - [`closeAllDialogs()`](#closealldialogs) — immediately reject all pending dialog promises and reset dialog state
-   - [`dialogEval(expr)`](#dialogevalexpr) — evaluate inside an active `Dialog[]` subsession
-   - [`exitDialog(retVal?)`](#exitdialogretval) — exit the current dialog and resume the main evaluation
-   - [`interrupt()`](#interrupt) — send a low-level interrupt signal to the kernel
-   - [`createSubsession(kernelPath?)`](#createsubsessionkernelpath) — spawn an independent parallel kernel session
-   - [`close()`](#close) — gracefully shut down the kernel and free resources
-   - [`isOpen` / `isDialogOpen`](#isopen--isdialogopen) — read-only status flags
-   - [Dynamic eval API](#dynamic-eval-api) — register expressions for automatic periodic evaluation
-5. [`WstpReader` — kernel-pushed side channel](#wstpreader)
-6. [`setDiagHandler(fn)`](#setdiaghandlerfn)
-5. [Usage examples](#usage-examples)
-   - [Basic evaluation](#basic-evaluation)
-   - [Interactive mode — In/Out history](#interactive-mode--inout-history)
-   - [Streaming output](#streaming-output)
-   - [Concurrent evaluations](#concurrent-evaluations)
+See [API.md](./API.md) for full API details, usage examples, and advanced features.
    - [Priority `sub()` calls](#priority-sub-calls)
    - [Abort a long computation](#abort-a-long-computation)
    - [Dialog subsessions](#dialog-subsessions)

package/binding.gyp

@@ -8,7 +8,15 @@
   "targets": [
     {
       "target_name": "wstp",
-      "sources": ["src/addon.cc"],
+      "sources": [
+        "src/addon.cc",
+        "src/diag.cc",
+        "src/wstp_expr.cc",
+        "src/drain.cc",
+        "src/evaluate_worker.cc",
+        "src/wstp_session.cc",
+        "src/wstp_reader.cc"
+      ],
 
       "include_dirs": [
         "<!@(node -p \"require('node-addon-api').include\")",

package/build.sh

@@ -98,25 +98,38 @@ echo "WSTP SDK      : $WSTP_SDK"
 NODE_LIB="$(node -p "process.execPath")"
 echo "Node lib      : $NODE_LIB"
 
-# ── compile source ────────────────────────────────────────────────────────────
-SOURCE="$SCRIPT_DIR/src/addon.cc"
-
-echo ""
-echo "Compiling $SOURCE …"
-
-clang++ \
-    -std=c++17 \
-    "${OPT_FLAGS[@]}" \
-    -Wall -Wextra \
-    -fPIC \
-    -fvisibility=hidden \
-    -DBUILDING_NODE_EXTENSION \
-    -DNAPI_DISABLE_CPP_EXCEPTIONS \
-    -I "$NODE_HEADERS" \
-    -I "$NAPI_INCLUDE" \
-    -I "$WSTP_SDK" \
-    -c "$SOURCE" \
-    -o "$OUT_DIR/addon.o"
+# ── compile sources ───────────────────────────────────────────────────────────
+SOURCES=(
+    "$SCRIPT_DIR/src/addon.cc"
+    "$SCRIPT_DIR/src/diag.cc"
+    "$SCRIPT_DIR/src/wstp_expr.cc"
+    "$SCRIPT_DIR/src/drain.cc"
+    "$SCRIPT_DIR/src/evaluate_worker.cc"
+    "$SCRIPT_DIR/src/wstp_session.cc"
+    "$SCRIPT_DIR/src/wstp_reader.cc"
+)
+
+OBJECTS=()
+for SRC in "${SOURCES[@]}"; do
+    BASE="$(basename "$SRC" .cc)"
+    OBJ="$OUT_DIR/${BASE}.o"
+    OBJECTS+=("$OBJ")
+    echo "Compiling $SRC …"
+    clang++ \
+        -std=c++17 \
+        "${OPT_FLAGS[@]}" \
+        -Wall -Wextra \
+        -fPIC \
+        -fvisibility=hidden \
+        -DBUILDING_NODE_EXTENSION \
+        -DNAPI_DISABLE_CPP_EXCEPTIONS \
+        -I "$NODE_HEADERS" \
+        -I "$NAPI_INCLUDE" \
+        -I "$WSTP_SDK" \
+        -I "$SCRIPT_DIR/src" \
+        -c "$SRC" \
+        -o "$OBJ"
+done
 
 echo "Linking $OUTPUT …"
 
@@ -124,7 +137,7 @@ clang++ \
     -dynamiclib \
     -undefined dynamic_lookup \
     -o "$OUTPUT" \
-    "$OUT_DIR/addon.o" \
+    "${OBJECTS[@]}" \
     "$WSTP_SDK/libWSTPi4.a" \
     -framework Foundation \
     -framework SystemConfiguration \

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wstp-node",
-  "version": "0.6.6",
+  "version": "0.7.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",