nwinread - Windows Event Log Reader

A native Node.js module for reading Windows event logs using the Windows Event Log API.

✨ Features:

• Universal Binaries: Built with N-API for compatibility across Node.js versions
• Precompiled Binaries: No compilation needed on installation
• High Performance: Native C++ implementation using Windows Event Log API
• Event Filtering: Filter events by Event ID for efficient processing
• Multiple Read Modes: Read from beginning, end, or specific position

Requirements

• Windows Vista/7/8/10/11 or Windows Server 2008/2012/2016/2019/2022
• Node.js 16+ (recommended for precompiled binaries)
• Node.js 10-14 (requires local compilation)

🐎 Node.js Version Support:

| Node.js | Status | Installation | |---------|--------|-------------| | 16.x | ✅ LTS | Instant (precompiled) | | 18.x | ✅ LTS | Instant (precompiled) | | 20.x | ✅ LTS | Instant (precompiled) | | 22.x | ✅ Current | Instant (precompiled) | | 10-14 | ⚠️ EOL | Requires build tools |

Build requirements (only for Node.js 10-14 or development):

• Visual Studio Build Tools or Visual Studio Community
• Python (for node-gyp)

Installation

🚀 Quick Install (Recommended)

npm install nwinread

✅ For Node.js 16+: Installs instantly using precompiled binaries
⚠️ For Node.js 10-14: Automatically compiles from source (requires build tools)

🔧 Development Install

git clone https://github.com/solzimer/nwinread.git
cd nwinread
npm install
npm run build
npm test

Install dependencies

npm install

Build native module

npm run build

Or build precompiled binaries

npm run prebuildify

## Usage

```javascript
const nwinread = require('nwinread');

// Read events from the end of the log (all events)
const result = nwinread.readEvents(
  'System',                    // Channel (System, Application, Security, etc.)  
  nwinread.START_MODE.END,     // Read mode
  0,                          // Watermark (for WATERMARK mode)
  10                          // Maximum number of events
);

// Read events with specific ID filter
const filteredResult = nwinread.readEvents(
  'System',                    // Channel
  nwinread.START_MODE.BEGINNING, // Read mode
  0,                          // Watermark
  20,                         // Maximum number of events
  [7045, 7034, 7036]          // Event IDs filter (optional)
);

console.log(`Found ${result.records.length} events`);
console.log(`Last Record ID: ${result.lastRecordId}`);

console.log(`Filtered events: ${filteredResult.records.length}`);

// Process events
result.records.forEach((event, index) => {
  console.log(`Event ${index + 1}:`);
  console.log(`  Record ID: ${event.recordId}`);
  console.log(`  XML: ${event.xml.substring(0, 100)}...`);
});

Read modes

• START_MODE.BEGINNING (0): Read from the beginning of the log
• START_MODE.END (1): Read from the end of the log
• START_MODE.WATERMARK (2): Read from a specific Record ID

API

readEvents(channel, mode, watermark, maxEvents, eventIds)

• channel (string): Event channel name (e.g.: 'System', 'Application', 'Security')
• mode (number): Read mode (use START_MODE constants)
• watermark (number): Record ID to start from (only for WATERMARK mode)
• maxEvents (number): Maximum number of events to read (1-10000)
• eventIds (array|null, optional): Array of Event IDs to filter. If null, undefined, or empty array, no filter is applied

Returns: Object with properties:

• records: Array of events with xml and recordId properties
• lastRecordId: ID of the last processed record

Event ID filtering examples

// No filter - all events
const allEvents = nwinread.readEvents('System', nwinread.START_MODE.BEGINNING, 0, 10);

// Filter only Windows service events
const serviceEvents = nwinread.readEvents('System', nwinread.START_MODE.BEGINNING, 0, 10, [7034, 7035, 7036, 7040, 7045]);

// Filter specific critical events
const criticalEvents = nwinread.readEvents('System', nwinread.START_MODE.BEGINNING, 0, 10, [1000, 1001, 1002]);

// Empty array = no filter (equivalent to null)
const noFilter = nwinread.readEvents('System', nwinread.START_MODE.BEGINNING, 0, 10, []);

Common Event IDs

• 7034: Service crashed
• 7035: Service start/stop control sent
• 7036: Service started/stopped
• 7040: Service startup type changed
• 7045: New service installed
• 1000: Application error
• 1001: Application hang
• 4624: Successful account logon (Security log)
• 4625: Failed account logon (Security log)

Development & Release Process

🏗️ For Contributors/Maintainers:

# Development workflow
npm run build       # Compile locally
npm run prebuildify # Generate precompiled binary for current platform
npm test           # Run tests
npm run verify     # Verify complete setup

# Release new version
npm version [patch|minor|major]  # Auto-generates prebuilds
git push origin --tags           # Triggers CI/CD for multi-platform builds

📦 Publishing Process:

1. Local Testing: npm test && npm run verify
2. Version Bump: npm version patch (auto-runs prebuildify)
3. Push Release: git push origin --tags
4. CI/CD Magic: GitHub Actions builds for all platforms & publishes automatically

Note: The prepublishOnly script ensures binaries are generated before any npm publish.

Testing

npm test

Troubleshooting

Installation Issues

1. "Still compiling on install":

   • ✅ Update to Node.js 16+ for precompiled binaries
   • ✅ Check npm ls nwinread shows correct version
   • ✅ Try npm cache clean --force && npm install

2. "Module not found":

   • ✅ Ensure Windows platform (module is Windows-only)
   • ✅ Try npm rebuild nwinread
   • ✅ Check administrator privileges if needed

Runtime Issues

3. Permission error: Some logs require administrator privileges
4. Channel not found: Verify that the channel name is correct
5. Old Node.js: Update to Node.js 16+ for best experience

Common channels

• System: System events
• Application: Application events
• Security: Security events (requires admin permissions)
• Setup: Installation events
• Microsoft-Windows-PowerShell/Operational: PowerShell events