VBSEngineJS

A VBScript engine implemented in TypeScript, supporting VBScript code execution in browser and Node.js environments.

Installation

npm install

Running Examples

See quick-start.md for more information.

API Reference

The VbsEngine class provides an API similar to Microsoft's MSScriptControl:

Methods

| Method | Description | |--------|-------------| | addCode(code: string) | Adds script code to the engine (function/class definitions) | | executeStatement(statement: string) | Executes a single VBScript statement | | run(procedureName: string, ...args) | Calls a function and returns the result | | eval(expression: string) | Evaluates an expression and returns the result | | addObject(name: string, object: unknown, addMembers?: boolean) | Exposes a JavaScript object to VBScript | | clearError() | Clears the last error | | destroy() | Cleans up resources (browser mode) |

Properties

| Property | Type | Description | |----------|------|-------------| | error | VbsError \| null | The last error that occurred, or null |

Example Usage

import { VbsEngine } from './src/index.ts';

const engine = new VbsEngine();

// Define functions
engine.addCode(`
  Function Multiply(a, b)
      Multiply = a * b
  End Function
  
  Class Calculator
      Public Function Add(x, y)
          Add = x + y
      End Function
  End Class
`);

// Call functions
const product = engine.run('Multiply', 6, 7);
console.log(product);  // 42

// Expose JavaScript objects
const myApp = {
  name: 'MyApp',
  version: '1.0.0',
  greet: (name: string) => `Hello, ${name}!`
};
engine.addObject('MyApp', myApp, true);

// Use exposed object in VBScript
engine.executeStatement('result = MyApp.greet("World")');
const result = engine.eval('result');
console.log(result);  // "Hello, World!"

// Error handling
engine.executeStatement('x = CInt("not a number")');
if (engine.error) {
  console.log('Error:', engine.error.description);
}

COM / ActiveX Integration (Node.js on Windows)

VBScript's CreateObject and GetObject depend on a host-provided COM backend. In Node.js, wire up @devscholar/node-ps1-dotnet before running scripts:

npm install @devscholar/node-ps1-dotnet

import { VbsEngine } from '@devscholar/vbs-engine-js';
import { ActiveXObject, GetObject } from '@devscholar/node-ps1-dotnet/activex';

// Expose COM constructors to the engine
globalThis.ActiveXObject = ActiveXObject;
globalThis.GetObject = GetObject;

const engine = new VbsEngine();

CreateObject

engine.executeStatement(`
  Set fso = CreateObject("Scripting.FileSystemObject")
  MsgBox fso.GetAbsolutePathName(".")
`);

GetObject — bind to a running instance

// GetObject(, "Excel.Application") — gets a running Excel instance
engine.executeStatement(`
  Set xl = GetObject(, "Excel.Application")
  MsgBox xl.Version
`);

GetObject — bind to a WMI moniker

engine.executeStatement(`
  Set wmi = GetObject("winmgmts:")
  For Each os In wmi.ExecQuery("SELECT * FROM Win32_OperatingSystem")
    MsgBox os.Caption & " " & os.Version
  Next
`);

GetObject — bind to a file

engine.executeStatement(`
  Set doc = GetObject("C:\Reports\sales.xls")
  MsgBox doc.Name
`);

Note: COM/ActiveX requires Windows. On other platforms CreateObject returns a dummy object and GetObject returns Nothing.

Security Warning

⚠️ Important Security Considerations

The VBScript engine executes arbitrary code provided by users or external sources. This presents significant security risks:

• Code Injection: Malicious VBScript code can access and modify JavaScript objects exposed via addObject()
• Infinite Loops: VBScript code can contain infinite loops that can hang the browser/Node.js process
• Resource Exhaustion: Poorly written scripts can consume excessive memory or CPU
• DOM Manipulation: In browser mode, scripts can access and modify the DOM

Engine Options

interface VbsEngineOptions {
  mode?: 'general' | 'browser';  // Default: 'general'
  injectGlobalThis?: boolean;    // Default: true
  maxExecutionTime?: number;     // Default: -1 (unlimited)
  
  // Browser mode only:
  parseScriptElement?: boolean;       // Default: true
  parseInlineEventAttributes?: boolean; // Default: true
  parseEventSubNames?: boolean;       // Default: true
  parseVbsProtocol?: boolean;         // Default: true
  overrideJsEvalFunctions?: boolean;  // Default: true
}

| Option | Type | Default | Description | |--------|------|---------|-------------| | mode | 'general' \| 'browser' | 'auto' | Engine mode. Auto-detects based on environment: 'browser' in browser, 'general' in Node.js. Use 'browser' for web applications | | injectGlobalThis | boolean | true | Enable IE-style global variable sharing between VBScript and JavaScript | | injectVBArrayToGlobalThis | boolean | true | Expose VBArray as globalThis.VBArray for legacy code compatibility | | maxExecutionTime | number | -1 | Maximum script execution time in milliseconds. -1 means unlimited | | parseScriptElement | boolean | true | Automatically process <script type="text/vbscript"> tags (browser mode) | | parseInlineEventAttributes | boolean | true | Process inline event attributes like onclick="vbscript:..." (browser mode) | | parseEventSubNames | boolean | true | Auto-bind event handlers from Sub names like Button1_OnClick (browser mode) | | parseVbsProtocol | boolean | true | Handle vbscript: protocol in links (browser mode) | | overrideJsEvalFunctions | boolean | true | Override JS eval functions (eval,setTimeout,setInterval) to support VBScript (browser mode) |

Example Usage

// General mode (Node.js or browser without auto-parsing)
const engine = new VbsEngine({
  injectGlobalThis: true,
  maxExecutionTime: 5000
});

// Browser mode (auto-parsing enabled)
const browserEngine = new VbsEngine({
  mode: 'browser',
  parseScriptElement: true,
  parseInlineEventAttributes: true,
  parseEventSubNames: true
});

Compatibility

See docs/compatibility.md for details.