Skip to content

Latest commit

 

History

History
132 lines (102 loc) · 4.13 KB

README.md

File metadata and controls

132 lines (102 loc) · 4.13 KB

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.