winax (node-activex)

If you install winax globally (npm install -g winax), you get access to the nodewscript command. This allows you to run legacy JScript files designed for the Windows Scripting Host (WSH) within a Node.js runtime, enabling the use of npm modules alongside WScript features.

Usage:

nodewscript [options] <Filename.js>

Key Differences & Limitations:

• Execution Model: Node.js is non-blocking/async, while WScript is linear. Node.js execution completes when the last statement is done AND all pending promises/callbacks are resolved.
• Implicit Properties: Unlike MS JScript, V8 (Node.js) does not support dynamic property checks on objects that aren't defined in ITypeInfo. An if (a.Prop) check might fail even if a.Prop is null or false if it's not explicitly marked as a property.
• Function Setters: The JScript syntax object("key") = "value" for setters will throw a syntax error in V8. You must use standard assignment object.key = "value".
• Bitness: nodewscript uses the same bitness as your installed Node.js version. If your scripts require 32-bit COM objects, use a 32-bit Node.js installation.

You can assign values to Excel ranges using two-dimensional JavaScript arrays.

Behavioral Rules:

• The second dimension is automatically deduced from the first array.
• To explicitly pass VT_EMPTY (empty cells), use null in the array.
• If the provided array dimensions are smaller than the target range, the missing cells will be emptied.
• If a single-row array is provided (e.g., [[1, 2, 3]]), it will duplicate across the rows/columns of the target range based on the range size.

var excel = new winax.Object("Excel.Application", { activate: true });
var wbk = excel.Workbooks.Add(template_filename);
var wsh = wbk.Worksheets.Item(1);

// Standard 2D assignment
wsh.Range("C3:E4").Value = [ ["C3", "D3", "E3" ], ["C4", "D4", "E4" ] ];

// Using null to leave cells empty
wsh.Range("C3:E4").Value = [ [null, "D3", "E3" ], "C4" ];

// Duplicating values across a range
wsh.Range("C3:F4").Value = [ [100, 200, 300, 400] ];

The winax.Variant class allows you to explicitly manage COM variant types. This is necessary for precise type control when interacting with COM APIs.

Supported Type Strings:

• int, uint, int8, char, uint8, uchar, byte, int16, short, uint16, ushort, int32, uint32, int64, long, uint64, ulong, currency, float, double, string, date, decimal, variant, null, empty.
• Use the prefix p (e.g., pshort) or the string 'byref' to indicate a reference to the current type.

Key Methods:

• new Variant(value, type): Creates a new variant.
• v.assign(value): Changes the content.
• v.cast(type): Casts the variant to a new type.
• v.clear(): Clears the variant content.
• winax.cast(value, type): A utility function to cast a value directly.

var winax = require('winax');
var Variant = winax.Variant;

// Create variant instance 
var v_short = new Variant(17, 'short');
var v_short_byref = new Variant(17, 'pshort');
var v_int_byref = new Variant(17, 'byref');
var v_byref = new Variant(v_short, 'byref');

// Create variant arrays
var v_array_of_variant = new Variant([1,'2',3]);
var v_array_of_short = new Variant([1,'2',3], 'short');
var v_array_of_string = new Variant([1,'2',3], 'string');

// Change variant content
var v_test = new Variant();
v_test.assign(17);
v_test.cast('string');
v_test.clear();

// Using cast function
var v_short_from_cast = winax.cast(17, 'short');

You can instantiate COM objects in two ways: using the global ActiveXObject constructor or using the winax.Object prototype.

When using the constructor, you can pass an optional configuration object:

• activate: (boolean, default false) If true, allows activating an existing object instance (via CoGetObject).
• getobject: (boolean, default false) If true, allows using the name of the file in the ROT (via GetAccessibleObject).
• type: (boolean, default true) If true, allows using type information to resolve conflicts between properties and methods (e.g., resolving rs.EOF).

// Using global function
var con = new ActiveXObject('ADODB.Connection');

// Using Object prototype
var winax = require('winax');
var con = new winax.Object('ADODB.Connection');

// With configuration options
var con = new ActiveXObject("Object.Name", {
	activate: false,
	getobject: false,
	type: true
});