winreglib: A C++ repository from TiDev

winreglib is a native C++ addon for Node.js for querying and watching Windows Registry keys. It provides a read-only, synchronous API for accessing the Windows Registry.

Features

Get, list, and watch registry keys without spawning reg.exe
Written in TypeScript
Packaged as an ESM module
Supports x64 (64-bit) and ia32 (32-bit) CPU architectures

Requirements

winreglib requires Node.js >=18.17.0 (Node-API 8) and ships with pre-built binaries for x64 and ia32 architectures. ARM-based architectures are not officially supported, but should technically work as long as you have the build tools installed.

Example

import winreglib from 'winreglib';

const key = 'HKLM\\SOFTWARE\\Microsoft\\Windows\\CurrentVersion';
const results = winreglib.list(key);

console.log(`Resolved ${results.resolvedRoot}`);
console.log(`${results.key} has ${results.subkeys.length} subkeys`);

console.log('  Subkeys:');
for (const subkey of results.subkeys) {
	console.log(`    ${subkey}`);
}

console.log('  Values:');
for (const valueName of results.values) {
	console.log(`    ${valueName} = ${winreglib.get(key, valueName)}`);
}

Supported Root Keys

Name	Abbreviation
`HKEY_CLASSES_ROOT`	`HKCR`
`HKEY_CURRENT_CONFIG`	`HKCC`
`HKEY_CURRENT_USER`	`HKCU`
`HKEY_CURRENT_USER_LOCAL_SETTINGS`
`HKEY_LOCAL_MACHINE`	`HKLM`
`HKEY_PERFORMANCE_DATA`
`HKEY_PERFORMANCE_NLSTEXT`
`HKEY_PERFORMANCE_TEXT`
`HKEY_USERS`	`HKU`

API

`get(key, valueName)`

Get a value for the given key and value name.

Argument	Type	Description
`key`	String	The key beginning with the root.
`valueName`	String	The name of the value to get.

Returns a String, Number, Buffer, Array.<String>, or null depending on the value.

If key or valueName is not found, an Error is thrown.

const value = winreglib.get(
  'HKLM\\SOFTWARE\\Microsoft\\Windows\\CurrentVersion',
  'ProgramFilesDir'
);

console.log(value);

C:\Program Files

`list(key)`

Retreives all subkeys and value names for a give key.

Argument	Type	Description
`key`	String	The key beginning with the root.

Returns an RegistryKey object:

type RegistryKey = {
	resolvedRoot: string;
	key: string;
	subkeys: string[];
	values: unknown[];
};

If key is not found, an Error is thrown.

const result = winreglib.list(
  'HKLM\\SOFTWARE\\Microsoft\\Windows\\CurrentVersion\\Setup
);

console.log(result);

{ resolvedRoot: 'HKEY_LOCAL_MACHINE',
  key:
    'HKEY_LOCAL_MACHINE\\SOFTWARE\\Microsoft\\Windows\\CurrentVersion\\Setup',
  subkeys:
   [ 'DPI',
     'ImageServicingData',
     'OC Manager',
     'OOBE',
     'PnpLockdownFiles',
     'PnpResources',
     'State',
     'Sysprep',
     'SysPrepExternal',
     'WindowsFeatures' ],
  values: [ 'LogLevel', 'BootDir' ] }

`watch(key)`

Watches a key for changes in subkeys or values.

Argument	Type	Description
`key`	String	The key beginning with the root.

Returns a handle (WinRegLibWatchHandle which extends EventEmitter) that emits "change" events. Call handle.stop() to stop watching the key.

const handle = winreglib.watch('HKLM\\SOFTWARE');
handle.on('change', evt => {
	console.log(`Got change! type=${evt.type} key=${evt.key}`);
	handle.stop();
});

The "change" event object contains a change "type" and the affected "key".

Event Type	Description
`add`	The `key` was added.
`change`	A subkey or value was added, changed, deleted, or permissions modified, but we don't know exactly what.
`delete`	The `key` was deleted.

watch() can track keys that do not exist and when they are created, a change event will be emitted. You can watch the same key multiple times, however each returned handle is unique and you must call handle.stop() for each.

Due to limitations of the Win32 API, watch() is unable to determine what actually changed during a change event type. You will need to call list() and cache the subkeys and values, then call list() again when a change is emitted and compare the before and after.

Note that watch() does not support recursively watching for changes. The Win32 API does support recursive watching, so this could be added in the future.

Advanced

Debug Logging

winreglib exposes an event emitter that emits debug log messages. This is intended to help debug issues under the hood. The average user will never need to use this, however it would be handy when filing a bug.

winreglib.on('log', msg => console.log(msg));

Alternatively, winreglib uses the amazing snooplogg debug logger where you simply set the SNOOPLOGG environment variable to winreglib (or *) and it will print the debug log to stderr.

$ SNOOPLOGG=winreglib node myapp.js
  6.150s winreglib:Watchman Initializing async work (thread 16764576586047274673)
  6.150s winreglib:Watchman::run Initializing run loop (thread 12502165600786624632)
  6.151s winreglib:Watchman::run Populating active copy (count=0)
  6.151s winreglib:Watchman::run Waiting on 2 objects...
  6.152s winreglib:list key="HKLM" subkey="SOFTWARE\Microsoft\Windows\CurrentVersion"
  6.152s winreglib:list 170 keys (max 30), 11 values (max 24)

Building `winreglib`

winreglib has two components: the public interface written in TypeScript and the native addon written in C++.

To compile the C++ code, you will need the Microsoft Visual Studio (not VSCode) or the Microsoft Build Tools. You may also need Python 3 installed.

Command	Description
`pnpm build`	Compiles the TypeScript and the Node.js native C++ addon for the current architecture
`pnpm build:bundle`	Compiles only the TypeScript code
`pnpm build:local`	Compiles only the Node.js native C++ addon
`pnpm rebuild:local`	Cleans and re-compiles only the Node.js native C++ addon

When publishing, the native C++ addon is prebuilt for x64 and ia32 architectures. Generally you shouldn't need be concerned with the prebuilt binaries, however the following commands will compile the prebuilds:

Command	Description
`pnpm build:prebuild`	Prebuild for x64 and ia32
`pnpm prebuild-arm`	Prebuild for arm (32-bit)
`pnpm prebuild-arm64`	Prebuild for arm64
`pnpm prebuild-ia32`	Prebuild for ia32 (x86 32-bit)
`pnpm prebuild-x64`	Prebuild for x64

Architecture

When winreglib is imported, it immediately spawns a background thread in the event the app is going to watch a key. If a key is added/changed/deleted, the background thread sends a message to the main thread which emits the change event.

Legal

Titanium is a registered trademark of TiDev Inc. All Titanium trademark and patent rights were transferred and assigned to TiDev Inc. on 4/7/2022. Please see the LEGAL information about using our trademarks, privacy policy, terms of usage and other legal information at https://tidev.io/legal.

tidev/winreglib