`native-reg`

In-process native node module for Windows registry access. It includes prebuilt binaries for Windows for x86 64-bit and 32-bit, and also ARM 64-bit (tested against unofficial Node.js builds, as it is not currently supported).

There are no fallbacks for other (future?) Windows targets, though requests are welcome.

If not running on Windows, the module will not fail to load in order to simplify cross-platform bundling, but it will assert if any of the functions are called.

Example

const reg = require('native-reg');

const key = reg.openKey(
  reg.HKCU,
  'Software\\MyCompany\\MySoftware',
  reg.Access.ALL_ACCESS);

const version = reg.getValue(key, 'Install', 'Version');

if (isOldVersion(version)) {
    reg.deleteTree(key, 'Install');
    
    const installKey = reg.createKey(key, 'Install', reg.Access.ALL_ACCESS);
    reg.setValueSZ(installKey, 'Version', newVersion);
    // ...
    reg.closeKey(installKey);
}

reg.closeKey(key);

API

Read each API's linked Windows documentation for details on functionality and usage.

Contents:

Errors
Constants:
Raw APIs:
Format Helpers
Formatted value APIs

Errors

The API initially validates the arguments with the standard node assert library:

try {
  // Should not be 'HKLM', but reg.HKLM or reg.HKEY.LOCAL_MACHINE
  reg.openKey('HKLM', 'SOFTWARE\\Microsoft\\Windows', reg.Access.READ);
  assert.fail();
} catch (e) {
  assert(e instanceof require('assert').AssertionError);
}

If the wrapped Windows API returns an error, with a couple of exceptions for commonly non-failure errors (e.g. key does not exist), are thrown as JS Errors with the generic error message, e.g.: Access is denied., but additional standard errno and syscall properties, for example, a common error is trying to use Access.ALL_ACCESS on reg.HKLM, which you need UAC elevation for:

try {
  // Assuming you are not running as administrator!
  reg.openKey(reg.HKLM, 'SOFTWARE\\Microsoft\\Windows', reg.Access.ALL_ACCESS);
  assert.fail();
} catch (e) {
  assert.strictEqual(e.message, 'Access is denied.');
  assert.strictEqual(e.errno, 5);
  assert.strictEqual(e.syscall, 'RegOpenKeyExW');
}

Constants

This library uses Typescript enums for constants, this generates a two way name <-> value mapping.

For example: Access.SET_VALUE is 0x0002, and Access[2] is "SET_VALUE".

`HKEY` enum

Exports the set of predefined HKEYs.

createKey, openKey, loadAppKey and openCurrentUser will return other values for HKEYs, which at the moment are objects with a single property native with the native HKEY handle as a V8 External value, for use in other native packages, or null after it is closed. For these values you can call closeKey once you are done to clean up early, but they will be closed by the garbage collector if you chose not to.

export enum HKEY {
  CLASSES_ROOT                   = 0x80000000,
  CURRENT_USER                   = 0x80000001,
  LOCAL_MACHINE                  = 0x80000002,
  USERS                          = 0x80000003,
  PERFORMANCE_DATA               = 0x80000004,
  PERFORMANCE_TEXT               = 0x80000050,
  PERFORMANCE_NLSTEXT            = 0x80000060,
  CURRENT_CONFIG                 = 0x80000005,
  DYN_DATA                       = 0x80000006,
  CURRENT_USER_LOCAL_SETTINGS    = 0x80000007,
}

Shorthands

Also exports the standard shorthand HKEY names:

export const HKCR = HKEY.CLASSES_ROOT;
export const HKCU = HKEY.CURRENT_USER;
export const HKLM = HKEY.LOCAL_MACHINE;
export const HKU = HKEY.USERS;

`isHKEY`

Helper returns if the argument is a valid-looking HKEY. Most APIs will throw an assertion error if hkey that does not return true for this is used.

Valid HKEY values are,

The values of the HKEY enum
Objects returned from createKey, openKey, loadAppKey and openCurrentUser
External values that represent HKEYs (for example, from another node addon)
Non-0 32-bit values that represent the pointer value of HKEYs (for example, from another node addon) - not that this is unreliable on 64-bit applications, and should be avoided.

export function isHKEY(hkey: any): boolean;

`Access` enum

Specifies access checks for opened or created keys. Not always enforced for opened keys:

Certain registry operations perform access checks against the security descriptor of the key, not the access mask specified when the handle to the key was obtained. For example, even if a key is opened with a samDesired of KEY_READ, it can be used to create registry keys if the key's security descriptor permits. In contrast, the RegSetValueEx function specifically requires that the key be opened with the KEY_SET_VALUE access right.

// from https://docs.microsoft.com/en-nz/windows/desktop/SysInfo/registry-key-security-and-access-rights
export enum Access {
  // Specific rights
  QUERY_VALUE         = 0x0001,
  SET_VALUE           = 0x0002,
  CREATE_SUB_KEY      = 0x0004,
  ENUMERATE_SUB_KEYS  = 0x0008,
  NOTIFY              = 0x0010,
  CREATE_LINK         = 0x0020,

  // WOW64. See https://docs.microsoft.com/en-nz/windows/desktop/WinProg64/accessing-an-alternate-registry-view
  WOW64_64KEY         = 0x0100,
  WOW64_32KEY         = 0x0200,

  // Generic rights.
  READ              = 0x2_0019,
  WRITE             = 0x2_0006,
  EXECUTE           = READ,

  ALL_ACCESS        = 0xF_003F,
}

`ValueType` enum

Types for registry values. See documentation.

export enum ValueType  {
  NONE                       = 0, // No value type
  SZ                         = 1, // Unicode nul terminated string
  EXPAND_SZ                  = 2, // Unicode nul terminated string
                                  // (with environment variable references)
  BINARY                     = 3, // Free form binary
  DWORD                      = 4, // 32-bit number
  DWORD_LITTLE_ENDIAN        = 4, // 32-bit number (same as REG_DWORD)
  DWORD_BIG_ENDIAN           = 5, // 32-bit number
  LINK                       = 6, // Symbolic Link (unicode)
  MULTI_SZ                   = 7, // Multiple Unicode strings
  RESOURCE_LIST              = 8, // Resource list in the resource map
  FULL_RESOURCE_DESCRIPTOR   = 9, // Resource list in the hardware description
  RESOURCE_REQUIREMENTS_LIST = 10,
  QWORD                      = 11, // 64-bit number
  QWORD_LITTLE_ENDIAN        = 11, // 64-bit number (same as REG_QWORD)
}

Raw APIs

These APIs fairly directly wrap the Windows API linked, only abstracting some of the allocation and general usage style.

The exception is enumKeyNames and enumValueNames which iterate to build a list and only return the names, and not other properties.

`Value` type

Raw registry values returned from queryValueRaw and getValueRaw are simply Node Buffers with an additional type property from ValueType:

export type Value = Buffer & { type: ValueType };

`createKey`

Wraps RegCreateKeyExW

Creates the specified registry key. If the key already exists, the function opens it. Note that key names are not case sensitive.

You must call closeKey on the result to clean up.

export function createKey(
  hkey: HKEY,
  subKey: string,
  access: Access,
  options: CreateKeyOptions = 0,
): HKEY;

export enum CreateKeyOptions {
  NON_VOLATILE = 0,
  VOLATILE = 1,
  CREATE_LINK = 2,
  BACKUP_RESTORE = 4,
}

`openKey`

Wraps RegOpenKeyExW

Opens the specified registry key. Note that key names are not case sensitive.

Returns null if subKey does not exist under hkey.

You must call closeKey on the result to clean up.

export function openKey(
  hkey: HKEY,
  subKey: string,
  access: Access,
  options: OpenKeyOptions = 0,
): HKEY | null;

export enum OpenKeyOptions {
  OPEN_LINK = 8,
}

`loadAppKey`

Wraps RegLoadAppKeyW

Loads the specified registry hive as an application hive.

You must call closeKey on the result to clean up.

export function loadAppKey(
  file: string,
  access: Access,
): HKEY;

`openCurrentUser`

Wraps RegOpenCurrentUser

Retrieves a handle to the HKEY_CURRENT_USER key for the user the current thread is impersonating.

Only makes sense to use if you have access to Windows user impersonation. Maybe take a look at my currently WIP Windows user account package.

You must call closeKey on the result to clean up.

export function openCurrentUser(access: Access): HKEY;

`enumKeyNames`

Wraps RegEnumKeyExW iterated to get the sub key names for a key.

Enumerates the subkeys of the specified open registry key.

export function enumKeyNames(hkey: HKEY): string[];

`enumValueNames`

Wraps RegEnumValueW iterated to get the value names for a key.

Enumerates the values for the specified open registry key.

export function enumValueNames(hkey: HKEY): string[];

`queryValueRaw`

Wraps RegQueryValueExW without additional parsing.

Retrieves the type and data for the specified value name associated with an open registry key.

You may want to use queryValue instead.

Returns null if valueName does not exist under hkey.

export function queryValueRaw(
  hkey: HKEY,
  valueName: string | null,
): Value | null;

`getValueRaw`

Wraps RegGetValueW without additional parsing.

Retrieves the type and data for the specified registry value.

You may want to use getValue instead.

Returns null if subKey or valueName does not exist under hkey.

export function getValueRaw(
  hkey: HKEY,
  subKey: string | null,
  valueName: string | null,
  flags: GetValueFlags = 0,
): Value | null;

export enum GetValueFlags {
  RT_ANY = 0xffff,
  RT_REG_NONE = 0x0001,
  RT_REG_SZ = 0x0002,
  RT_REG_EXPAND_SZ = 0x0004,
  RT_REG_BINARY = 0x0008,
  RT_REG_DWORD = 0x0010,
  RT_REG_MULTI_SZ = 0x0020,
  RT_REG_QWORD = 0x0040,
  RT_DWORD = RT_REG_DWORD | RT_REG_BINARY,
  RT_QWORD = RT_REG_QWORD | RT_REG_BINARY,

  NO_EXPAND = 0x10000000,
  // ZEROONFAILURE = 0x20000000, // doesn't make sense here
  SUBKEY_WOW6464KEY = 0x00010000,
  SUBKEY_WOW6432KEY = 0x00020000,
}

`setValueRaw`

Wraps RegSetValueExW

Sets the data and type of a specified value under a registry key.

export function setValueRaw(
  hkey: HKEY,
  valueName: string | null,
  valueType: ValueType,
  data: Buffer,
): void;

`renameKey`

Wraps RegRenameKey

Changes the name of the specified registry key.

export function renameKey(
  hkey: HKEY,
  subKey: string | null,
  newSubKey: string,
): void;

`copyTree`

Wraps RegCopyTreeW

Copies the specified registry key, along with its values and subkeys, to the specified destination key.

export function copyTree(
  hkeySrc: HKEY,
  subKey: string | null,
  hkeyDest: HKEY,
): void;

`deleteKey`

Wraps RegDeleteKeyW

Deletes a subkey and its values. Note that key names are not case sensitive.

Returns true if the key existed before it was deleted.

export function deleteKey(
  hkey: HKEY,
  subKey: string,
): boolean;

`deleteTree`

Wraps RegDeleteTreeW

Deletes the subkeys and values of the specified key recursively.

Returns true if the key existed before it was deleted.

export function deleteTree(
  hkey: HKEY,
  subKey: string | null,
): boolean;

`deleteKeyValue`

Wraps RegDeleteKeyValueW

Removes the specified value from the specified registry key and subkey.

Returns true if the value existed before it was deleted.

export function deleteKeyValue(
  hkey: HKEY,
  subKey: string,
  valueName: string,
): boolean;

`deleteValue`

Wraps RegDeleteValueW

Removes a named value from the specified registry key. Note that value names are not case sensitive.

Returns true if the value existed before it was deleted.

export function deleteValue(
  hkey: HKEY,
  valueName: string | null,
): boolean;

`closeKey`

Wraps RegCloseKey

Closes a handle to the specified registry key.

For convenience, null or undefined values are allowed and ignored.

export function closeKey(hkey: HKEY | null | undefined): void;

Format helpers

`parseValue`

Returns the JS-native value for common Value types:

SZ, EXPAND_SZ -> string
BINARY -> Buffer
DWORD / DWORD_LITTLE_ENDIAN -> number
DWORD_BIG_ENDIAN -> number
MULTI_SZ -> string[]
QWORD / QWORD_LITTLE_ENDIAN -> bigint

Throws an assertion error if the type is not one of the above!

For convenience, passes through null so missing values don't have to be specially treated.

export type ParsedValue = number | bigint | string | string[] | Buffer;
export function parseValue(value: Value | null): ParsedValue | null;

`parseString`

Parses SZ and EXPAND_SZ (etc.) registry values.

export function parseString(value: Buffer): string;

`parseMultiString`

Parses MULTI_SZ registry values.

export function parseMultiString(value: Buffer): string[];

`formatString`

Formats a string to SZ, EXPAND_SZ (etc.) format.

export function formatString(value: string): Buffer;

`formatMultiString`

Formats an array of strings to MULTI_SZ format.

export function formatMultiString(values: string[]): Buffer;

`formatDWORD`

Formats a number to DWORD / DWORD_LITTLE_ENDIAN format.

export function formatDWORD(value: number): Buffer;

`formatQWORD`

Formats a number or bigint to QWORD format.

export function formatQWORD(value: number | bigint): Buffer;

Formatted value APIs

These APIs wrap the raw value APIs with the formatting helpers.

`setValue{Type}`

A set of wrappers that sets the registry value using setValueRaw with the appropriate ValueType and format helper.

For example, setValueSZ is setValueRaw(hkey, valueName, ValueType.SZ, formatString(value)).

export function setValueSZ(
  hkey: HKEY,
  valueName: string | null,
  value: string,
): void;
export function setValueEXPAND_SZ(
  hkey: HKEY,
  valueName: string | null,
  value: string,
): void;
export function setValueMULTI_SZ(
  hkey: HKEY,
  valueName: string | null,
  value: string[],
): void;
export function setValueDWORD(
  hkey: HKEY,
  valueName: string | null,
  value: number,
): void;
export function setValueQWORD(
  hkey: HKEY,
  valueName: string | null,
  value: number | bigint,
): void;

`getValue`

Wraps getValueRaw in parseValue.

export function getValue(
  hkey: HKEY,
  subKey: string | null,
  valueName: string | null,
  flags: GetValueFlags = 0,
): ParsedValue | null;

`queryValue`

Wraps queryValueRaw in parseValue.

export function queryValue(
  hkey: HKEY,
  valueName: string | null,
): ParsedValue | null;

native-reg

native-reg

Example

API

Errors

Constants

HKEY enum

Shorthands

isHKEY

Access enum

ValueType enum

Raw APIs

Value type

createKey

openKey

loadAppKey

openCurrentUser

enumKeyNames

enumValueNames

queryValueRaw

getValueRaw

setValueRaw

renameKey

copyTree

deleteKey

deleteTree

deleteKeyValue

deleteValue

closeKey

Format helpers

parseValue

parseString

parseMultiString

formatString

formatMultiString

formatDWORD

formatQWORD

Formatted value APIs

setValue{Type}

getValue

queryValue

Readme

Keywords

Package Sidebar

Install

Repository

Homepage

DownloadsWeekly Downloads

Version

License

Unpacked Size

Total Files

Last publish

Collaborators

`native-reg`

`HKEY` enum

`isHKEY`

`Access` enum

`ValueType` enum

`Value` type

`createKey`

`openKey`

`loadAppKey`

`openCurrentUser`

`enumKeyNames`

`enumValueNames`

`queryValueRaw`

`getValueRaw`

`setValueRaw`

`renameKey`

`copyTree`

`deleteKey`

`deleteTree`

`deleteKeyValue`

`deleteValue`

`closeKey`

`parseValue`

`parseString`

`parseMultiString`

`formatString`

`formatMultiString`

`formatDWORD`

`formatQWORD`

`setValue{Type}`

`getValue`

`queryValue`

Weekly Downloads