wstp-node 0.4.5 → 0.6.0

package/README.md

@@ -30,6 +30,7 @@ const { WstpSession, WstpReader, setDiagHandler } = require('./build/Release/wst
    - [`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)
@@ -97,7 +98,7 @@ The script automatically locates the WSTP SDK inside the default Wolfram install
 node test.js
 ```
 
-Expected last line: `All 36 tests passed.`
+Expected last line: `All 52 tests passed.`
 
 A more comprehensive suite (both modes + In/Out + comparison) lives in `tmp/tests_all.js`:
 
@@ -105,7 +106,7 @@ A more comprehensive suite (both modes + In/Out + comparison) lives in `tmp/test
 node tmp/tests_all.js
 ```
 
-Expected last line: `All 56 tests passed.`
+Expected last line: `All 41 tests passed.`
 
 ### 5. Quick smoke test
 
@@ -487,6 +488,35 @@ session.isDialogOpen: boolean  // true while inside a Dialog[] subsession
 
 ---
 
+### Dynamic eval API
+
+Register Wolfram Language expressions for automatic periodic evaluation during
+cell computations.  A `RunScheduledTask` in the kernel periodically calls
+`Dialog[]`; the C++ layer intercepts each `BEGINDLGPKT`, evaluates all
+registered expressions inline, stores the results, and closes the dialog.
+
+| Method | Description |
+|--------|-------------|
+| `registerDynamic(id, expr)` | Register (or upsert) an expression for periodic evaluation |
+| `unregisterDynamic(id)` | Remove one registration by id |
+| `clearDynamicRegistry()` | Remove all registrations and clear results buffer |
+| `getDynamicResults()` | Return `Record<string, DynResult>` and clear buffer |
+| `setDynamicInterval(ms)` | Set the ScheduledTask period (0 = off) |
+| `setDynAutoMode(auto)` | `true` (default) = C++ handles dialogs; `false` = legacy JS path |
+| `dynamicActive` | Read-only: `true` when registry is non-empty and interval > 0 |
+
+```ts
+interface DynResult {
+    value:      string;  // string-form result
+    timestamp:  number;  // Unix timestamp (ms)
+    error?:     string;  // set if evaluation failed
+}
+```
+
+See [API.md](API.md#dynamic-eval-api) for full documentation.
+
+---
+
 ## `WstpReader`
 
 A reader that **connects to** a named WSTP link created by the kernel (via `LinkCreate`)

package/index.d.ts

@@ -77,6 +77,37 @@ export interface EvalOptions {
      * @param level  The nesting depth that just closed.
      */
     onDialogEnd?: (level: number) => void;
+    /**
+     * When `true`, any `BEGINDLGPKT` received during a non-interactive
+     * evaluation is automatically closed in C++ without informing the JS
+     * layer.  Use for `VsCodeRender`, handler-install, and `sub()` calls
+     * that must never block on a Dialog[] (prevents Pattern C deadlocks).
+     */
+    rejectDialog?: boolean;
+}
+
+/**
+ * One captured Dynamic[] result returned by `getDynamicResults()`.
+ */
+export interface DynResult {
+    /** String-form result returned by the kernel for this expression. */
+    value:      string;
+    /** Unix timestamp (ms) when this result was evaluated. */
+    timestamp:  number;
+    /** Set if evaluation failed (e.g. timeout, `$Failed`). */
+    error?:     string;
+}
+
+/**
+ * Optional options for subWhenIdle().
+ */
+export interface SubWhenIdleOptions {
+    /**
+     * Maximum number of milliseconds to wait in the queue before the
+     * returned Promise rejects with a timeout error.
+     * Omit or set to 0 for no timeout (wait indefinitely).
+     */
+    timeout?: number;
 }
 
 /**
@@ -202,6 +233,36 @@ export class WstpSession {
      */
     sub(expr: string): Promise<WExpr>;
 
+    /**
+     * Queue a background evaluation that runs only when the kernel is truly idle.
+     *
+     * Unlike `sub()`, which runs *before* any queued `evaluate()` calls,
+     * `subWhenIdle()` runs only *after* ALL pending `evaluate()` and `sub()`
+     * calls have completed.  This makes it safe for background queries
+     * (e.g. global-symbol coloring, auto-complete) that must not compete with
+     * active cell evaluations.
+     *
+     * If the kernel is idle at call time the query starts immediately;
+     * otherwise it is queued and executes as soon as the kernel becomes
+     * fully idle again.  Multiple `subWhenIdle()` calls are executed FIFO.
+     *
+     * If the session is closed while the request is still queued the Promise
+     * rejects with `"Session is closed"`.
+     *
+     * @param expr  Wolfram Language expression string to evaluate.
+     * @param opts  Optional: `{ timeout?: number }` — ms before the Promise
+     *              rejects with `"subWhenIdle: timeout"` if the kernel has
+     *              not become idle within that window.
+     * @returns     Promise that resolves with the WExpr result,
+     *              identical in shape to the value returned by `sub()`.
+     *
+     * @example
+     * session.subWhenIdle('Names["Global`*"]').then(result => {
+     *     // safe background query — never races with evaluate()
+     * });
+     */
+    subWhenIdle(expr: string, opts?: SubWhenIdleOptions): Promise<WExpr>;
+
     /**
      * Launch an independent child kernel as a new WstpSession.
      *
@@ -220,6 +281,79 @@ export class WstpSession {
 
     /** True while the link is open and the kernel is running. */
     readonly isOpen: boolean;
+
+    /**
+     * The OS process ID of the WolframKernel child process.
+     *
+     * Useful for external monitoring or force-terminating a stale kernel
+     * after a restart.  Returns `0` if the PID could not be determined
+     * at session-construction time (rare, non-fatal fallback).
+     *
+     * The PID is captured once during `new WstpSession()` and does not
+     * change; it remains set even after `close()` so callers can reference
+     * it in cleanup paths.
+     */
+    readonly kernelPid: number;
+
+    // ── Dynamic eval API ────────────────────────────────────────────────────
+
+    /**
+     * Register (or update) a Wolfram Language expression to be evaluated
+     * automatically every time the kernel enters a Dialog[] interrupt.
+     *
+     * @param id    Unique identifier for this registration (e.g. `"x"`).
+     * @param expr  Wolfram Language expression string (e.g. `"ToString[x]"`).
+     */
+    registerDynamic(id: string, expr: string): void;
+
+    /**
+     * Remove a previously registered Dynamic expression by id.
+     * Has no effect if the id was never registered.
+     */
+    unregisterDynamic(id: string): void;
+
+    /** Remove all registered Dynamic expressions. */
+    clearDynamicRegistry(): void;
+
+    /**
+     * Consume and return all results accumulated since the last call.
+     *
+     * Each key is a registration `id`; each value is the most recent
+     * `DynResult` for that expression.  Calling this clears the internal
+     * buffer so subsequent calls return only new results.
+     *
+     * @returns  A plain object mapping id → DynResult.
+     */
+    getDynamicResults(): Record<string, DynResult>;
+
+    /**
+     * Set the auto-interrupt period (in ms) for the Dynamic timer thread.
+     *
+     * The background thread sends `WSInterruptMessage` to the kernel every
+     * `ms` milliseconds while an evaluation is in progress and the registry
+     * is non-empty.  Set to `0` to disable.
+     *
+     * @param ms  Interval in milliseconds (0 = off).
+     */
+    setDynamicInterval(ms: number): void;
+
+    /**
+     * Switch the Dialog[] handling mode.
+     *
+     * - `true` (default): C++ intercepts every `BEGINDLGPKT` and evaluates
+     *   all registered expressions inline — no JS round-trip required.
+     * - `false`: Falls back to the legacy JS callback path
+     *   (`onDialogBegin` / `dialogEval` / `exitDialog`).
+     *
+     * @param auto  `true` to enable automatic C++ handling, `false` for legacy.
+     */
+    setDynAutoMode(auto: boolean): void;
+
+    /**
+     * `true` when the Dynamic registry is non-empty **and** the timer
+     * interval is greater than zero (i.e. auto-interrupts are active).
+     */
+    readonly dynamicActive: boolean;
 }
 
 /**

package/package.json

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

package/scripts/diagnose-windows.ps1

@@ -13,8 +13,10 @@ $files = @("wstp.h", "wstp64i4s.lib")
 $searchRoots = @(
     "C:\Program Files\Wolfram Research",
     "C:\Program Files (x86)\Wolfram Research",
-    "$env:LOCALAPPDATA\Programs\Wolfram Research"
-)
+    "$env:LOCALAPPDATA\Programs\Wolfram Research",
+    "C:\Program Files\Wolfram Research\Mathematica",
+    "C:\Program Files\Wolfram Research\Wolfram Engine"
+) | Where-Object { (Test-Path $_) -and -not (Test-Path (Join-Path $_ "wsl.exe")) }
 
 $found = @{}
 

package/scripts/wstp_dir.js

@@ -22,67 +22,89 @@ function resolve () {
 
   // ── 2. Windows ──────────────────────────────────────────────────────────
   if (process.platform === 'win32') {
-    const base = process.env.PROGRAMFILES || 'C:\\Program Files';
+    const pf   = process.env.PROGRAMFILES        || 'C:\\Program Files';
+    const pf86 = process.env['PROGRAMFILES(X86)'] || 'C:\\Program Files (x86)';
+    const local = process.env.LOCALAPPDATA        || '';
 
-    // Wolfram products to try, in priority order
-    const products = [
-      'Wolfram Research\\Wolfram Engine',
-      'Wolfram Research\\Mathematica',
-      'Wolfram Research\\WolframEngine',
-    ];
+    // All candidate root directories to search under
+    const searchRoots = [
+      path.join(pf,   'Wolfram Research'),
+      path.join(pf86, 'Wolfram Research'),
+      local ? path.join(local, 'Programs', 'Wolfram Research') : null,
+    ].filter(Boolean);
 
-    for (const product of products) {
-      const productDir = path.join(base, product);
-      let entries;
-      try { entries = fs.readdirSync(productDir); } catch (e) { continue; }
-
-      // Find version subfolders (e.g. "14.2", "13.1") — any dir starting with a digit
-      const versions = entries
-        .filter(d => {
-          if (!/^\d/.test(d)) return false;
-          try { return fs.statSync(path.join(productDir, d)).isDirectory(); } catch (e) { return false; }
-        })
-        .sort()
-        .reverse();
-
-      if (!versions.length) {
-        // Help diagnose: show what IS there
-        process.stderr.write(
-          `wstp_dir: found "${productDir}" but no version subfolder.\n` +
-          `  Contents: ${entries.join(', ') || '(empty)'}\n`
-        );
-        continue;
-      }
+    // Product subfolder names to try
+    const productNames = ['Mathematica', 'Wolfram Engine', 'WolframEngine'];
+
+    for (const root of searchRoots) {
+      let rootEntries;
+      try { rootEntries = fs.readdirSync(root); } catch (e) { continue; }
+
+      for (const product of productNames) {
+        const productDir = path.join(root, product);
+        let entries;
+        try { entries = fs.readdirSync(productDir); } catch (e) { continue; }
+
+        // Skip if this looks like WSL rather than a Wolfram product
+        if (entries.includes('wsl.exe') || entries.includes('wslservice.exe')) {
+          process.stderr.write(
+            `wstp_dir: skipping "${productDir}" — looks like WSL, not Wolfram\n`
+          );
+          continue;
+        }
 
-      const wstp = path.join(
-        productDir, versions[0],
-        'SystemFiles', 'Links', 'WSTP', 'DeveloperKit',
-        'Windows-x86-64', 'CompilerAdditions'
-      );
-      if (!fs.existsSync(path.join(wstp, 'wstp.h')) &&
-          !fs.existsSync(path.join(wstp, 'wstp64i4s.lib'))) {
-        process.stderr.write(
-          `wstp_dir: found version "${versions[0]}" but WSTP DeveloperKit missing.\n` +
-          `  Expected these files inside:\n` +
-          `    ${wstp}\n` +
-          `      wstp.h          (C header)\n` +
-          `      wstp64i4s.lib   (static import library)\n`
+        // Find version subfolders (e.g. "14.2", "13.1") — dirs starting with a digit
+        const versions = entries
+          .filter(d => {
+            if (!/^\d/.test(d)) return false;
+            try { return fs.statSync(path.join(productDir, d)).isDirectory(); } catch (e) { return false; }
+          })
+          .sort()
+          .reverse();
+
+        if (!versions.length) {
+          process.stderr.write(
+            `wstp_dir: "${productDir}" has no version subfolder — skipping\n` +
+            `  Contents: ${entries.join(', ')}\n`
+          );
+          continue;
+        }
+
+        const wstp = path.join(
+          productDir, versions[0],
+          'SystemFiles', 'Links', 'WSTP', 'DeveloperKit',
+          'Windows-x86-64', 'CompilerAdditions'
         );
-        continue;
+
+        const hasHeader = fs.existsSync(path.join(wstp, 'wstp.h'));
+        const hasLib    = fs.existsSync(path.join(wstp, 'wstp64i4s.lib'));
+
+        if (!hasHeader || !hasLib) {
+          process.stderr.write(
+            `wstp_dir: found version "${versions[0]}" but WSTP DeveloperKit missing.\n` +
+            `  Expected both files inside:\n` +
+            `    ${wstp}\n` +
+            `      wstp.h          (C header)   — ${hasHeader ? 'FOUND' : 'MISSING'}\n` +
+            `      wstp64i4s.lib   (import lib)  — ${hasLib    ? 'FOUND' : 'MISSING'}\n`
+          );
+          continue;
+        }
+
+        return wstp;
       }
-      return wstp;
     }
 
     throw new Error(
-      `WSTP DeveloperKit not found.\n` +
-      `Searched under "${base}" for: ${products.join(', ')}\n\n` +
-      `The build needs these two files:\n` +
+      `WSTP DeveloperKit not found on Windows.\n\n` +
+      `The build requires two files from the Wolfram Engine / Mathematica installation:\n` +
       `  wstp.h          (C header)\n` +
       `  wstp64i4s.lib   (static import library)\n\n` +
-      `Run the diagnostic script to find them:\n` +
+      `These live inside:\n` +
+      `  <WolframEngine>\\<version>\\SystemFiles\\Links\\WSTP\\DeveloperKit\\Windows-x86-64\\CompilerAdditions\\\n\n` +
+      `Run the diagnostic to find them:\n` +
       `  powershell -ExecutionPolicy Bypass -File scripts\\diagnose-windows.ps1\n\n` +
-      `Then set WSTP_DIR to the folder containing both files and retry:\n` +
-      `  set WSTP_DIR=C:\\Program Files\\Wolfram Research\\Wolfram Engine\\14.2\\SystemFiles\\Links\\WSTP\\DeveloperKit\\Windows-x86-64\\CompilerAdditions\n` +
+      `Then set WSTP_DIR and retry:\n` +
+      `  set WSTP_DIR=<path shown above>\n` +
       `  npm install`
     );
   }