wstp-node 0.4.6 → 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.6",
+  "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",