{"id":28100355,"url":"https://github.com/tidev/winreglib","last_synced_at":"2025-05-13T18:33:45.845Z","repository":{"id":42207491,"uuid":"185246228","full_name":"tidev/winreglib","owner":"tidev","description":"Windows Registry Utility Library","archived":false,"fork":false,"pushed_at":"2025-05-06T03:30:19.000Z","size":1083,"stargazers_count":6,"open_issues_count":0,"forks_count":2,"subscribers_count":14,"default_branch":"main","last_synced_at":"2025-05-06T04:24:31.176Z","etag":null,"topics":["npm-package","windows-registry","winreg"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tidev.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":"tidev","liberapay":"tidev"}},"created_at":"2019-05-06T17:59:49.000Z","updated_at":"2025-05-06T03:30:15.000Z","dependencies_parsed_at":"2024-09-16T05:12:17.889Z","dependency_job_id":"2acb4805-34c0-44ce-a8d0-c033eb6a9aad","html_url":"https://github.com/tidev/winreglib","commit_stats":null,"previous_names":["appcelerator/winreglib"],"tags_count":15,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tidev%2Fwinreglib","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tidev%2Fwinreglib/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tidev%2Fwinreglib/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tidev%2Fwinreglib/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tidev","download_url":"https://codeload.github.com/tidev/winreglib/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254003554,"owners_count":21997900,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["npm-package","windows-registry","winreg"],"created_at":"2025-05-13T18:33:45.180Z","updated_at":"2025-05-13T18:33:45.829Z","avatar_url":"https://github.com/tidev.png","language":"C++","funding_links":["https://github.com/sponsors/tidev","https://liberapay.com/tidev"],"categories":[],"sub_categories":[],"readme":"\u003cbr\u003e\n\u003cdiv align=\"center\"\u003e\n\t\u003cimg width=\"640\" height=\"240\" src=\"media/winreglib.webp\" alt=\"winreglib\"\u003e\n\u003c/div\u003e\n\u003cbr\u003e\n\n`winreglib` is a native C++ addon for Node.js for querying and watching Windows\nRegistry keys. It provides a read-only, synchronous API for accessing the\nWindows Registry.\n\n## Features\n\n  - Get, list, and watch registry keys _without_ spawning `reg.exe`\n  - Written in TypeScript\n  - Packaged as an ESM module\n  - Supports x64 (64-bit) and ia32 (32-bit) CPU architectures\n\n## Requirements\n\n`winreglib` requires Node.js \u003e=18.17.0 (Node-API 8) and ships with pre-built\nbinaries for x64 and ia32 architectures. ARM-based architectures are not\nofficially supported, but should technically work as long as you have the\nbuild tools installed.\n\n## Example\n\n```javascript\nimport winreglib from 'winreglib';\n\nconst key = 'HKLM\\\\SOFTWARE\\\\Microsoft\\\\Windows\\\\CurrentVersion';\nconst results = winreglib.list(key);\n\nconsole.log(`Resolved ${results.resolvedRoot}`);\nconsole.log(`${results.key} has ${results.subkeys.length} subkeys`);\n\nconsole.log('  Subkeys:');\nfor (const subkey of results.subkeys) {\n\tconsole.log(`    ${subkey}`);\n}\n\nconsole.log('  Values:');\nfor (const valueName of results.values) {\n\tconsole.log(`    ${valueName} = ${winreglib.get(key, valueName)}`);\n}\n```\n\n## Supported Root Keys\n\n| Name                               | Abbreviation |\n| ---------------------------------- | ------------ |\n| `HKEY_CLASSES_ROOT`                | `HKCR`       |\n| `HKEY_CURRENT_CONFIG`              | `HKCC`       |\n| `HKEY_CURRENT_USER`                | `HKCU`       |\n| `HKEY_CURRENT_USER_LOCAL_SETTINGS` |              |\n| `HKEY_LOCAL_MACHINE`               | `HKLM`       |\n| `HKEY_PERFORMANCE_DATA`            |              |\n| `HKEY_PERFORMANCE_NLSTEXT`         |              |\n| `HKEY_PERFORMANCE_TEXT`            |              |\n| `HKEY_USERS`                       | `HKU`        |\n\n## API\n\n### `get(key, valueName)`\n\nGet a value for the given key and value name.\n\n| Argument    | Type   | Description                      |\n| ----------- | ------ | -------------------------------- |\n| `key`       | String | The key beginning with the root. |\n| `valueName` | String | The name of the value to get.    |\n\nReturns a `String`, `Number`, `Buffer`, `Array.\u003cString\u003e`, or `null`\ndepending on the value.\n\nIf `key` or `valueName` is not found, an `Error` is thrown.\n\n```js\nconst value = winreglib.get(\n  'HKLM\\\\SOFTWARE\\\\Microsoft\\\\Windows\\\\CurrentVersion',\n  'ProgramFilesDir'\n);\n\nconsole.log(value);\n```\n\n```\nC:\\Program Files\n```\n\n### `list(key)`\n\nRetreives all subkeys and value names for a give key.\n\n| Argument | Type   | Description                      |\n| -------- | ------ | -------------------------------- |\n| `key`    | String | The key beginning with the root. |\n\nReturns an `RegistryKey` object:\n\n```\ntype RegistryKey = {\n\tresolvedRoot: string;\n\tkey: string;\n\tsubkeys: string[];\n\tvalues: unknown[];\n};\n```\n\nIf `key` is not found, an `Error` is thrown.\n\n```js\nconst result = winreglib.list(\n  'HKLM\\\\SOFTWARE\\\\Microsoft\\\\Windows\\\\CurrentVersion\\\\Setup\n);\n\nconsole.log(result);\n```\n\n```js\n{ resolvedRoot: 'HKEY_LOCAL_MACHINE',\n  key:\n    'HKEY_LOCAL_MACHINE\\\\SOFTWARE\\\\Microsoft\\\\Windows\\\\CurrentVersion\\\\Setup',\n  subkeys:\n   [ 'DPI',\n     'ImageServicingData',\n     'OC Manager',\n     'OOBE',\n     'PnpLockdownFiles',\n     'PnpResources',\n     'State',\n     'Sysprep',\n     'SysPrepExternal',\n     'WindowsFeatures' ],\n  values: [ 'LogLevel', 'BootDir' ] }\n```\n\n### `watch(key)`\n\nWatches a key for changes in subkeys or values.\n\n| Argument | Type   | Description                      |\n| -------- | ------ | -------------------------------- |\n| `key`    | String | The key beginning with the root. |\n\nReturns a handle (`WinRegLibWatchHandle` which extends `EventEmitter`) that\nemits `\"change\"` events. Call `handle.stop()` to stop watching the key.\n\n```js\nconst handle = winreglib.watch('HKLM\\\\SOFTWARE');\nhandle.on('change', evt =\u003e {\n\tconsole.log(`Got change! type=${evt.type} key=${evt.key}`);\n\thandle.stop();\n});\n```\n\nThe `\"change\"` event object contains a change `\"type\"` and the affected\n`\"key\"`.\n\n| Event Type | Description                        |\n| ---------- | ---------------------------------- |\n| `add`      | The `key` was added.               |\n| `change`   | A subkey or value was added, changed, deleted, or permissions modified, but we don't know exactly what. |\n| `delete`   | The `key` was deleted.             |\n\n`watch()` can track keys that do not exist and when they are created, a\nchange event will be emitted. You can watch the same key multiple times,\nhowever each returned handle is unique and you must call `handle.stop()` for\neach.\n\nDue to limitations of the Win32 API, `watch()` is unable to determine what\nactually changed during a `change` event type. You will need to call `list()`\nand cache the subkeys and values, then call `list()` again when a change is\nemitted and compare the before and after.\n\nNote that `watch()` does not support recursively watching for changes. The\nWin32 API does support recursive watching, so this could be added in the\nfuture.\n\n## Advanced\n\n### Debug Logging\n\n`winreglib` exposes an event emitter that emits debug log messages. This is\nintended to help debug issues under the hood. The average user will never\nneed to use this, however it would be handy when filing a bug.\n\n```js\nwinreglib.on('log', msg =\u003e console.log(msg));\n```\n\nAlternatively, `winreglib` uses the amazing [`snooplogg`][2] debug logger\nwhere you simply set the `SNOOPLOGG` environment variable to `winreglib` (or\n`*`) and it will print the debug log to `stderr`.\n\n```bash\n$ SNOOPLOGG=winreglib node myapp.js\n  6.150s winreglib:Watchman Initializing async work (thread 16764576586047274673)\n  6.150s winreglib:Watchman::run Initializing run loop (thread 12502165600786624632)\n  6.151s winreglib:Watchman::run Populating active copy (count=0)\n  6.151s winreglib:Watchman::run Waiting on 2 objects...\n  6.152s winreglib:list key=\"HKLM\" subkey=\"SOFTWARE\\Microsoft\\Windows\\CurrentVersion\"\n  6.152s winreglib:list 170 keys (max 30), 11 values (max 24)\n```\n\n### Building `winreglib`\n\n`winreglib` has two components: the public interface written in TypeScript and\nthe native addon written in C++.\n\nTo compile the C++ code, you will need the Microsoft Visual Studio (not VSCode)\nor the Microsoft Build Tools. You may also need Python 3 installed.\n\n| Command              | Description |\n| -------------------- | ----------- |\n| `pnpm build`         | Compiles the TypeScript and the Node.js native C++ addon for the current architecture |\n| `pnpm build:bundle`  | Compiles only the TypeScript code |\n| `pnpm build:local`   | Compiles only the Node.js native C++ addon |\n| `pnpm rebuild:local` | Cleans and re-compiles only the Node.js native C++ addon |\n\nWhen publishing, the native C++ addon is prebuilt for x64 and ia32\narchitectures. Generally you shouldn't need be concerned with the prebuilt\nbinaries, however the following commands will compile the prebuilds:\n\n| Command               | Description                    |\n| --------------------- | ------------------------------ |\n| `pnpm build:prebuild` | Prebuild for x64 and ia32      |\n| `pnpm prebuild-arm`   | Prebuild for arm (32-bit)      |\n| `pnpm prebuild-arm64` | Prebuild for arm64             |\n| `pnpm prebuild-ia32`  | Prebuild for ia32 (x86 32-bit) |\n| `pnpm prebuild-x64`   | Prebuild for x64               |\n\n### Architecture\n\nWhen `winreglib` is imported, it immediately spawns a background thread in the\nevent the app is going to watch a key. If a key is added/changed/deleted, the\nbackground thread sends a message to the main thread which emits the change\nevent.\n\n## Legal\n\nTitanium 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.\n\n[1]: https://github.com/tidev/winreglib/blob/master/LICENSE\n[2]: https://www.npmjs.com/package/snooplogg\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftidev%2Fwinreglib","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftidev%2Fwinreglib","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftidev%2Fwinreglib/lists"}