@devscholar/vbs-engine-js 0.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (7) hide show
  1. package/LICENSE.md +21 -0
  2. package/README.md +232 -0
  3. package/dist/vbs-engine.js +5259 -0
  4. package/dist/vbs-engine.js.map +1 -0
  5. package/dist/vbs-engine.umd.cjs +25 -0
  6. package/dist/vbs-engine.umd.cjs.map +1 -0
  7. package/package.json +37 -0
package/LICENSE.md ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 DevScholar
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,232 @@
1
+ # VBSEngineJS
2
+
3
+ ⚠️ This project is still in alpha stage. Expect breaking changes.
4
+
5
+ A VBScript engine implemented in TypeScript, supporting VBScript code execution in browser and Node.js environments.
6
+
7
+ ## Installation
8
+
9
+ ```bash
10
+ npm install
11
+ ```
12
+
13
+ ## Running Examples
14
+
15
+ ### HTML Example (Browser)
16
+
17
+ Start the development server and open the example page:
18
+
19
+ ```bash
20
+ npm run dev
21
+ ```
22
+
23
+ Then open your browser and visit:
24
+ - `http://localhost:5173/examples/index.html` - Full demo with MsgBox, InputBox, clock, and event handlers
25
+
26
+ Or directly:
27
+ ```bash
28
+ npx vite examples/index.html
29
+ ```
30
+
31
+ ### Node.js Example
32
+
33
+ Run the Node.js demo that shows how to use VBScript with Node.js modules:
34
+
35
+ ```bash
36
+ npx tsx examples/node-demo.ts
37
+ ```
38
+
39
+ This example demonstrates:
40
+ - Defining VBScript functions with `addCode()`
41
+ - Calling VBScript functions with `run()`
42
+ - Accessing Node.js modules (path, fs) from VBScript via globalThis
43
+
44
+ ## Quick Start
45
+
46
+ ### Browser Environment
47
+
48
+ Write VBScript code using the `<script type="text/vbscript">` or `<script language="vbscript">` tag in HTML:
49
+
50
+ ```html
51
+ <!DOCTYPE html>
52
+ <html>
53
+ <head>
54
+ <meta charset="UTF-8">
55
+ <title>VBScript Demo</title>
56
+ <script type="module">
57
+ import { VbsEngine } from './src/index.ts';
58
+ new VbsEngine({ mode: 'browser' });
59
+ </script>
60
+ </head>
61
+ <body>
62
+ <div id="output"></div>
63
+
64
+ <script type="text/vbscript">
65
+ msg = "Hello from VBScript!"
66
+
67
+ Function Add(a, b)
68
+ Add = CLng(a) + CLng(b)
69
+ End Function
70
+
71
+ Sub ShowOutput()
72
+ Set el = document.getElementById("output")
73
+ el.innerHTML = msg & "<br>" & "2 + 3 = " & Add(2, 3)
74
+ End Sub
75
+
76
+ Call ShowOutput()
77
+ </script>
78
+ </body>
79
+ </html>
80
+ ```
81
+
82
+ Start the development server:
83
+
84
+ ```bash
85
+ npm run dev
86
+ ```
87
+
88
+ Then visit `http://localhost:5173/examples/index.html`.
89
+
90
+ ### Node.js Environment
91
+
92
+ ```typescript
93
+ import { VbsEngine } from './src/index.ts';
94
+
95
+ const engine = new VbsEngine();
96
+
97
+ // Add function definitions
98
+ engine.addCode(`
99
+ Function Add(a, b)
100
+ Add = a + b
101
+ End Function
102
+ `);
103
+
104
+ // Call a function
105
+ const result = engine.run('Add', 10, 20);
106
+ console.log('Result:', result); // 30
107
+
108
+ // Execute a statement
109
+ engine.executeStatement('name = "World"');
110
+
111
+ // Evaluate an expression
112
+ const greeting = engine.eval('"Hello, " & name & "!"');
113
+ console.log(greeting); // "Hello, World!"
114
+ ```
115
+
116
+ Run with `npx tsx examples/node-demo.ts`.
117
+
118
+ ## API Reference
119
+
120
+ The `VbsEngine` class provides an API similar to Microsoft's MSScriptControl:
121
+
122
+ ### Methods
123
+
124
+ | Method | Description |
125
+ |--------|-------------|
126
+ | `addCode(code: string)` | Adds script code to the engine (function/class definitions) |
127
+ | `executeStatement(statement: string)` | Executes a single VBScript statement |
128
+ | `run(procedureName: string, ...args)` | Calls a function and returns the result |
129
+ | `eval(expression: string)` | Evaluates an expression and returns the result |
130
+ | `addObject(name: string, object: unknown, addMembers?: boolean)` | Exposes a JavaScript object to VBScript |
131
+ | `clearError()` | Clears the last error |
132
+ | `destroy()` | Cleans up resources (browser mode) |
133
+
134
+ ### Properties
135
+
136
+ | Property | Type | Description |
137
+ |----------|------|-------------|
138
+ | `error` | `VbsError \| null` | The last error that occurred, or null |
139
+
140
+ ### Example Usage
141
+
142
+ ```typescript
143
+ import { VbsEngine } from './src/index.ts';
144
+
145
+ const engine = new VbsEngine();
146
+
147
+ // Define functions
148
+ engine.addCode(`
149
+ Function Multiply(a, b)
150
+ Multiply = a * b
151
+ End Function
152
+
153
+ Class Calculator
154
+ Public Function Add(x, y)
155
+ Add = x + y
156
+ End Function
157
+ End Class
158
+ `);
159
+
160
+ // Call functions
161
+ const product = engine.run('Multiply', 6, 7);
162
+ console.log(product); // 42
163
+
164
+ // Expose JavaScript objects
165
+ const myApp = {
166
+ name: 'MyApp',
167
+ version: '1.0.0',
168
+ greet: (name: string) => `Hello, ${name}!`
169
+ };
170
+ engine.addObject('MyApp', myApp, true);
171
+
172
+ // Use exposed object in VBScript
173
+ engine.executeStatement('result = MyApp.greet("World")');
174
+ const result = engine.eval('result');
175
+ console.log(result); // "Hello, World!"
176
+
177
+ // Error handling
178
+ engine.executeStatement('x = CInt("not a number")');
179
+ if (engine.error) {
180
+ console.log('Error:', engine.error.description);
181
+ }
182
+ ```
183
+
184
+ ## Engine Options
185
+
186
+ ```typescript
187
+ interface VbsEngineOptions {
188
+ mode?: 'general' | 'browser'; // Default: 'general'
189
+ injectGlobalThis?: boolean; // Default: true
190
+ maxExecutionTime?: number; // Default: -1 (unlimited)
191
+
192
+ // Browser mode only:
193
+ parseScriptElement?: boolean; // Default: true
194
+ parseInlineEventAttributes?: boolean; // Default: true
195
+ parseEventSubNames?: boolean; // Default: true
196
+ parseVbsProtocol?: boolean; // Default: true
197
+ overrideJsEvalFunctions?: boolean; // Default: true
198
+ }
199
+ ```
200
+
201
+ | Option | Type | Default | Description |
202
+ |--------|------|---------|-------------|
203
+ | `mode` | `'general' \| 'browser'` | `'general'` | Engine mode. Use `'browser'` for web applications |
204
+ | `injectGlobalThis` | `boolean` | `true` | Enable IE-style global variable sharing between VBScript and JavaScript |
205
+ | `maxExecutionTime` | `number` | `-1` | Maximum script execution time in milliseconds. `-1` means unlimited |
206
+ | `parseScriptElement` | `boolean` | `true` | Automatically process `<script type="text/vbscript">` tags (browser mode) |
207
+ | `parseInlineEventAttributes` | `boolean` | `true` | Process inline event attributes like `onclick="vbscript:..."` (browser mode) |
208
+ | `parseEventSubNames` | `boolean` | `true` | Auto-bind event handlers from Sub names like `Button1_OnClick` (browser mode) |
209
+ | `parseVbsProtocol` | `boolean` | `true` | Handle `vbscript:` protocol in links (browser mode) |
210
+ | `overrideJsEvalFunctions` | `boolean` | `true` | Override JS eval functions to support VBScript (browser mode) |
211
+
212
+ ### Example Usage
213
+
214
+ ```typescript
215
+ // General mode (Node.js or browser without auto-parsing)
216
+ const engine = new VbsEngine({
217
+ injectGlobalThis: true,
218
+ maxExecutionTime: 5000
219
+ });
220
+
221
+ // Browser mode (auto-parsing enabled)
222
+ const browserEngine = new VbsEngine({
223
+ mode: 'browser',
224
+ parseScriptElement: true,
225
+ parseInlineEventAttributes: true,
226
+ parseEventSubNames: true
227
+ });
228
+ ```
229
+
230
+ ## Compatibility
231
+
232
+ See [docs/compatibility.md](docs/compatibility.md) for details.