rage-edit
🗃 Simple access to, and manipulation of, the Windows Registry. With promises. Without rage.
Installation
npm install rage-edit
Keep in mind before using
Structure and naming (keys & values) in the Windows Registry
Please be advised that the key
and value
terminology from the Windows registry might be confusing because it's different than the naming widely used in the world of JS. Windows registry is much like file system with folders and files, or XML, rather than JSON.
In JSON, key
usually stands for name of the property that stores a value
.
In the Windows registry, key
is like a folder (or the path to it) that can contain multiple value
s, which are kind of like files. value
has a name and the data content it stores (and type of the data).
So when refering to value
, its name is often meant rather than the data it holds.
To lessen the confusion, we're often using terms like value entry, value name, name of the value entry, etc... and path stands for the path of the key.
Default value (empty string)
Every windows registry key always contains a default value with the empty string ''
for name.
// read default valueawait Registry// write default valueawait Registry
See Default values section for more
Case in/sensitivity
Key path and value names are case insensitive, you can interchangeably read, write and delete with any combination of casing. rage-edit
lowercases everything by default.
await Registry // returns the dataawait Registry // returns the data
See Case sensitivity section for more
API
Registry
class
Only the Registry
class is exported (both named and default export)
// ES Modules way// CJS wayvar Registry =
It is modelled after ES6 Map
class with methods like .get()
, .set()
, .delete()
and a few others. Those can be used in two modes - static and instance.
Static mode
// Creates Overwatch key inside HKLM\SOFTWARE if it doesn't exist yet.// Also creates default value inside it (with data 'Soldiers, scientists, adventurers, oddities...')await Registry// Gets value of 'Scientists' from key 'HKLM\Software\Overwatch'await Registry// Creates/rewrites value entry 'hq' with data 'Switzerland' at 'HKLM\Software\Overwatch'await Registry// Creates/rewrites value 'Leader' at 'HKLM\Software\Overwatch\Backwatch'await Registry// Retrieves the 'leader' value from // NOTE: case insensitivityawait Registry
Instance mode
// Creates the instance but does not yet create the Overwatch key if it doesn't exists yet.var reg = 'HKLM\\Software\\Overwatch'// Creates default value inside the key (with data 'Soldiers, scientists, adventurers, oddities...')await reg// Gets value of 'Scientists' from key 'HKLM\Software\Overwatch'await reg// Creates/rewrites value entry 'hq' with data 'Switzerland' at 'HKLM\Software\Overwatch'await reg// Creates/rewrites value 'Leader' at 'HKLM\Software\Overwatch\Backwatch'await reg// Retrieves the 'leader' value from // NOTE: case insensitivityawait reg
Static methods
.get(path, [name])
Retrieves key from path
or content of the name
d value entry at the path.
Parameters:
path
to a key to retrieve or from where to retrieve the value.[name]
of the value to retrieve. Optional. Default value (empty string) is retrieved if omitted.
Returns:
Promise<object>
Example
// Retrieves key 'HKLM\Software\Overwatch'.Registry// Retrieves default value from 'HKLM\Software\Overwatch'.Registry// Retrieves value 'Scientists' from 'HKLM\Software\Overwatch'.Registry
.has(path, [name])
Just like .get()
but returns boolean depending on existence of the key or value.
Returns:
Promise<bool>
.delete(path, [name])
Deletes a registry key at the given path
or deletes a name
d value entry within this key.
Parameters
path
of the key to delete, or the key that hosts the value to delete.[name]
of the value to delete.
Returns
Promise
Example
// Deletes subkey 'Blackwatch' (with all of its subkeys and values) inside 'HKLM\Software\Overwatch'Registry// Deletes value 'Scientists' from 'HKLM\Software\Overwatch'Registry// Deletes default value entry (empty string, can be omitted) from 'HKLM\Software\Overwatch'Registry// Deletes the key 'HKLM\Software\Overwatch' and all of its subkeys and valuesRegistry
.set(path[, name[, data[, type]]])
Creates or rewrites a key or name
d value inside a key at the given path
.
If a key at the path doesn't exist it will be created as if Registry.set(path)
was called beforehand.
Creating new keys also creates an empty default value inside it (that's how windows registry works) as if Registry.set(path, '', '', 'REG_SZ')
was called with it.
Parameters
path
of the key where the value should be created.[name]
of the value to create or modify. Optional. To modify the key's default value (empty string) use''
.[data]
to store in the value entry. Optional.[type]
of the storeddata
. Optional. It is inferred from thedata
if this parameter is omitted.
JS type | Registry type |
---|---|
String |
REG_SZ , REG_EXPAND_SZ |
Number |
REG_DWORD |
Array<String> |
REG_MULTI_SZ |
Buffer , Uint8Array , ArrayBuffer |
REG_BINARY |
Returns
Promise
Example
// Creates or rewrites value entry named 'Leader' with 'Jack Morrison' data of 'REG_SZ' type that is infered from the String data.// inside the key 'HKLM\Software\Overwatch'. Also creates the key if it didn't existRegistry// Creates or rewrites value 'Scientists' with data 'Angela Ziegler\0Winston\0Mei-Ling Zhou' of type 'REG_MUTLI_SZ' (inferred from Array data)Registry// Re/writes data of default value entry.Registry// Creates a new subkey 'Blackwatch' inside 'HKLM\Software\Overwatch' and creates default value with data Mysterious branch of Overwatch'Registry
Static properties
DEFAULT = ''
String used to represent the name of the default value.
VALUES = '$values'
String used for naming values key in simple mode
Constructor, instance mode
new Registry(path)
var reg = 'HKLM\\Software\\Overwatch'regreg
Instance methods
#get([subpath][, name])
Retrieves key from the instance's path or from a given subpath
.
Or instead retrieves content of a value at the path if name
is defined.
Parameters:
[subpath]
Path to a subkey where the value is stored. Optional. Defaults tothis.path
.[name]
of the value to retrieve. Optional. Default value (empty string) is retrieved if omitted.
Returns:
Promise<object>
Example
// Creates instance of Registry, using 'HKLM\Software\Overwatch' path for all operations by default.var reg = 'HKLM\\Software\\Overwatch'// Retrieves key 'HKLM\Software\Overwatch'.reg// Retrieves default value from 'HKLM\Software\Overwatch'.reg// Retrieves value 'Scientists' from 'HKLM\Software\Overwatch'.reg// Retrieves subkey 'Blackwatch' inside 'HKLM\Software\Overwatch'.reg// Retrieves default value from 'HKLM\Software\Overwatch\Backwatch'reg// Retrieves value 'Leader' from 'HKLM\Software\Overwatch\Backwatch'reg
#has([subpath][, name])
Just like .get()
but returns boolean depending on existence of the sub/key or value.
Returns:
Promise<bool>
#delete([subpath][, name])
Deletes the instance's registry key or subkey at given subath
.
Alternatively deletes name
d value from the key.
Parameters:
[subpath]
Path to a subkey where the value is stored. Optional. Defaults tothis.path
.[name]
of the value to delete.
Returns:
Promise
#set([subpath][, name[, data[, type]]])
Creates or rewrites name
d value inside instance's path or at given subpath
key.
Alternatively creates subkey at subpath
if name
and data
are undefined.
Parameters
[subpath]
Path of the subkey to create (or where to set value). Optional ifname
is defined.subpath
has to always begin with a backslash\
otherwise it will be mistaken asname
[name]
of the value to create or modify. Optional ifsubpath
is defined in which case no value is created, only the subkey. To modify key's default value (empty string) use''
.[data]
to be stored in the value entry. Optional.[type]
of the storeddata
. Optional. It is inferred from thedata
if this parameter is omitted.
Returns:
Promise
Example
// Creates instance of Registry, using 'HKLM\Software\Overwatch' path for all operations by default.var reg = 'HKLM\\Software\\Overwatch'// Creates the key (if it didn't exist)reg// Creates 'disbanded' value with no datareg// Creates or rewrites value entry named 'Leader' with 'Jack Morrison' data of 'REG_SZ' type that is infered from the String data.// inside the key 'HKLM\Software\Overwatch'. Also creates the key if it didn't existreg// Creates or rewrites value 'Scientists' with data 'Angela Ziegler\0Winston\0Mei-Ling Zhou' of type 'REG_MUTLI_SZ' (inferred from Array data)reg// Re/writes data of default value entry.reg// Creates a key 'HKLM\Software\Overwatch\Blackwatch' (if it didn't exist)reg// Creates a new subkey 'Blackwatch' inside 'HKLM\Software\Overwatch' and creates default value with data Mysterious branch of Overwatch'reg// Creates/rewrites value 'Leader' at 'HKLM\Software\Overwatch\Backwatch'reg
Instance properties
path
Full path of current key path.
hive
Short name of the current hive like HKCU
.
Output format
Retrieving data from the registry poses a complication. Format of the output cannot be as straight forward as JSONs nested structure because the registry better resembles an XML tree where each node can have both a children nodes and also attributes. A Windows registry key can host sub keys as well as value entries, both of which can have the same names leading to possible collisions.
Due to that rage-edit
offers two types of output formats. simple
and complex
. By default simple
is enabled globally for all calls.
It can be set as a global default for all method calls, or specified manually in each method call in the options
argument.
// change format globallyRegistryformat = 'complex'// or individuallyRegistry
Simple
Simple output tries to resemble JSON at much as possible while trying to avoid collisions with the names of keys and values.
Key names are properties of the object. The key is represented by (stub of) another object. This is useful when calling Registry.get()
in recursive mode.
Values are stored in $values
object of name:data
pairs, where value name is the property, value data is the content of that property, and type is omitted.
Warning: $values
might be still conflicting since $
is a valid character in key paths. You can change $values
to be whatever else by changing Registry.VALUES
. e.g. Registry.VALUES = '__$$NO_CONFLICT_VALUES'
So if your key has a subkey named version
and also a value named version
, you will be able to access both of them without collision with output.version
and output.$values.version
.
// Registry.get('HKCR\\.jpg') $values: '': 'jpegfile' 'content type': 'image/jpeg' 'perceivedtype': 'image' 'openwithprogids': ... 'persistenthandler': ...
This format is optimized for nesting to allow you to do this.
Note: .get()
calls are not recursive by default due to performance reasons. The following snippet serves as an example of how output can be nested, but the HKLM
hive contains enormous amounts of data and thus is not recommended to be queried recursively.
// Gets default value (empty string) of HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Lock Screen\FeedManagervar software = await Registrysoftwaremicrosoftwindowscurrentversion'Lock Screen'feedmanager$values''
Complex
Offers comprehensive output and first and foremost contains types of value entries since every value entry is represented by {name, data, type}
object in a values
array.
// Registry.get('HKCR\\.jpg', {format: 'complex'}) keys: 'openwithprogids': keys: ... values: ... 'persistenthandler': keys: ... values: ... values: name: '' data: 'jpegfile' type: 'REG_SZ' name: 'content type' data: 'image/jpeg' type: 'REG_SZ' name: 'perceivedtype' data: 'image' type: 'REG_SZ'
Nesting with this format is much more verbose.
// Gets default value (empty string) of HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Lock Screen\FeedManagervar software = await Registrysoftwarekeysmicrosoftkeyswindowskeyscurrentversionkeys'Lock Screen'keysfeedmanagervalues''
Caveats, edge cases & the weirdness of Windows registry
Windows registry has its fair share of footguns that you should be aware of. Not to mention the danger of damaging keys and values that are critical for the proper operation of the OS.
Friendly reminder about HKCR, HKLM, 64b and Wow6432Nodes
HKCR
is a pointer to HKLM\Software\Classes
. Use it to access all users.
HKCU
is a pointer to HKUS\${UserSid}
Use it to access only current user.
Therefore
HKCU\Software\Classes
is a pointer to HKUS\${UserSid}\Software\Classes
which is another pointer to HKUS\${UserSid}_Classes
.
But on on 64b it points to subkey Wow6432Nodes
, so HKUS\${UserSid}\Software\Classes
is a pointer to HKUS\${UserSid}_Classes\Wow6432Node
on 64b systems.
Example:
original key | pointer to | b |
---|---|---|
HKCU\Software\Classes\CLSID |
HKUS\${UserSid}_Classes\CLSID |
32b |
HKCU\Software\Classes\CLSID |
HKUS\${UserSid}_Classes\Wow6432Node\CLSID |
64b |
Default values
Every key has a default value (empty string) which is represented as an empty string. I.e. name of the value entry is empty string ''
. You might also come across it as a (Default)
in the regedit
program or in reg
command.
await Registry$values'' // value of the default value at given pathawait Registry // get default value from the pathawait Registry // set default value's data
It is by default of type REG_SZ
.
Creation of a new key also creates default value inside it. The value's name is an empty string ''
and the data content is also an empty string.
As long as the default value has any data, it will act as any other value and will show up in getValues()
.
await Registryawait Registry // true - default value exists in this keyawait Registry // '' - default value has data of an empty stringawait Registry$values // [''] - list of values in this key, so far only the default value
practical example:
// creates new key and default value '' of type REG_SZawait Registry// creates or updates default value of type REG_SZ, inside key HKLM\SOFTWARE\Overwatch (also creates the key if it doesn't exists) await Registry// creates or updates default value of type REG_EXPAND_SZ, inside key HKLM\SOFTWARE\Overwatch (also creates the key if it doesn't exists)await Registry// sidenote: value name is '', value data is 'Soldiers, scientists, adventurers, oddities...')
Default value cannot be deleted. Attempting to do so (Registry.delete(path, '')
) will not actually delete the entry, but only its data. Or rather it will set the data to some sort of undefined
or null
(can be seen as (value not set)
in regedit
), which is unique to the default value.
In this state, the default value returns undefined
when queried with get()
it will not be listed in $values
, despite actually existing - has()
always returns true
.
await Registryawait Registry // true - the value always existsawait Registry // undefined - the value has no dataawait Registry$value // [] - empty array
Restricted access, administrator permissions
Write and delete operation outside HKCU
hive (Current user) as well as reading certain hives require the app to run with administrator privileges.
try await Registry console await Registry console catcherr console
Error suppresion
rage-edit
deliberately suppresses error The system was unable to find the specified registry key or value
that is thrown by the reg
command when a non-existent value or key is queried. Instead the promise is resolve with undefined
.
All other errors (especially Access is denied
) are thrown as expected and the promise will be rejected.
Case sensitivity
Windows Registry is case insensitive. That applies to key paths and value names. But there are some edge cases. rage-edit
by default transforms all key paths and value names (not the actual data of value entry) to lowercase by default to prevent confusion.
This does not affect input - you can still use all-caps paths and value names with uppercased characters.
// both ways work and return the same valueawait Registry // returns the dataawait Registry // returns the dataawait Registry // returns the dataawait Registry // returns the datavar key = await Registrykeypersistenthandler // contains the datakeyPersistentHandler // undefinedkey$values'content type' // contains the datakey$values'Content Type' // undefined
The lowercasing can be turned off
// globallyRegistrylowercase = false// or per requestvar key = await Registrykey$values'Content Type'
Why?
Underlying REG command doesn't distinguish between lowercase or upper case. Direct queries for a certain value with /v
argument always mimic the case in which the key and value name are inputted and never return the true case of the value name. In this case PERCEIVEDTYPE
, PerceivedType
and perceivedtype
reg query HKCR\.JPG /v PERCEIVEDTYPE
HKEY_CLASSES_ROOT\.JPG
PERCEIVEDTYPE REG_SZ image
reg query HKCR\.Jpg /v PerceivedType
HKEY_CLASSES_ROOT\.Jpg
PerceivedType REG_SZ image
reg query HKCR\.jpg /v perceivedtype
HKEY_CLASSES_ROOT\.jpg
perceivedtype REG_SZ image
But omiting /v
(value name) argument to query all contents of the key would return value entries with their true names (in this case PerceivedType
).
C:\WINDOWS\system32>reg query HKCR\.jpg
HKEY_CLASSES_ROOT\.jpg
(Default) REG_SZ jpegfile
Content Type REG_SZ image/jpeg
PerceivedType REG_SZ image
This however could cause performance issues (querying whole key when only single value is needed isn't a good idea) and the insensitive nature of Windows Registry lead rage-edit
to deliberately lowercase all paths and value names to prevent situations like this:
// rage-edit by default transforms all value names to lower case to prevent having to do this:var key = await Registryvar version = key$values'VERSION' || key$values'Version' || key$values'version'
Type infering and conversions
rage-edit
automatically picks a registry value type for you, based in the data you're storing, if you don't specify the type for yourself.
RegistryRegistry RegistryRegistryRegistry RegistryRegistryRegistry RegistryRegistry
REG_DWORD and REG_QWORD
Windows Registry allows storing 32b values as DWORDS and 64b values as QWORDS.
Javascript Number only support 53 bit integers.
DWORD values are automatically converted to and from Number by rage-edit
automatically.
QWORD values cannot be converted due to JS limitations. The reg
command also retrieves the values in hex Ox
notation and rage-edit
does not change that.
var value = 1234 RegistryRegistry Registry // 1234Registry // '0x4D2'
Join the discussion
We're at Discord and Gitter. Come join us to discuss features, bugs and more.
Credits
Made by Mike Kovařík, Mutiny.cz