VBSEngineJS

This project is in Beta stage.

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);
}

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'	'general'	Engine mode. 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.