{"_id":"@bun-win32/propsys","_rev":"3-3b27d18f908bd961789885f8cd559d91","name":"@bun-win32/propsys","dist-tags":{"latest":"2.0.1"},"versions":{"1.0.0":{"name":"@bun-win32/propsys","version":"1.0.0","keywords":["bun","ffi","win32","windows","propsys","bindings","typescript","dll"],"author":"Stev Peifer <stev@bell.net>","license":"MIT","_id":"@bun-win32/propsys@1.0.0","maintainers":[{"name":"obscuritysrl","email":"stev@bell.net"}],"homepage":"https://github.com/ObscuritySRL/bun-win32#readme","bugs":{"url":"https://github.com/ObscuritySRL/bun-win32/issues"},"dist":{"shasum":"38bdb96efc3931dfcb5d42bfe09292e4a6273b03","tarball":"https://registry.npmjs.org/@bun-win32/propsys/-/propsys-1.0.0.tgz","fileCount":6,"integrity":"sha512-ErQ08qUx6SphwVzsXSw1yErTqMXLIOMwqJxyzOn98WR29CUIm0Ws20bhp43Let55KMLlAzdZ1heJWh9SOfGcjQ==","signatures":[{"sig":"MEUCIG+uaB/jdu/UlSpNAjlwB+3XUDoRZ00V+KGNI0Rj581+AiEA4/TS0zG/ZQOVBhKjIDzAwUdSOtauQpKLotwEvnffxUk=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":100045},"main":"./index.ts","type":"module","module":"index.ts","shasum":"38bdb96efc3931dfcb5d42bfe09292e4a6273b03","engines":{"bun":">=1.1.0"},"exports":{".":"./index.ts"},"private":false,"scripts":{"example:windows-sort-visualizer":"bun ./example/windows-sort-visualizer.ts","example:property-system-diagnostic":"bun ./example/property-system-diagnostic.ts"},"_npmUser":{"name":"obscuritysrl","email":"stev@bell.net"},"_integrity":"sha512-ErQ08qUx6SphwVzsXSw1yErTqMXLIOMwqJxyzOn98WR29CUIm0Ws20bhp43Let55KMLlAzdZ1heJWh9SOfGcjQ==","repository":{"url":"git://github.com/ObscuritySRL/bun-win32.git","type":"git","directory":"packages/propsys"},"_npmVersion":"10.8.3","description":"Zero-dependency, zero-overhead Win32 PROPSYS bindings for Bun (FFI) on Windows.","directories":{},"sideEffects":false,"_nodeVersion":"24.3.0","dependencies":{"@bun-win32/core":"1.1.2"},"_hasShrinkwrap":false,"devDependencies":{"@types/bun":"latest"},"peerDependencies":{"typescript":"^5"},"_npmOperationalInternal":{"tmp":"tmp/propsys_1.0.0_1779073013357_0.6320359957037329","host":"s3://npm-registry-packages-npm-production"}},"2.0.0":{"name":"@bun-win32/propsys","version":"2.0.0","keywords":["bun","ffi","win32","windows","propsys","bindings","typescript","dll"],"author":"Stev Peifer <stev.p@outlook.com>","license":"MIT","_id":"@bun-win32/propsys@2.0.0","maintainers":[{"name":"obscuritysrl","email":"stev.p@outlook.com"}],"homepage":"https://github.com/ObscuritySRL/bun-win32#readme","bugs":{"url":"https://github.com/ObscuritySRL/bun-win32/issues"},"dist":{"shasum":"bd416bf466525e6ccf10466f2dc5ea30ed718ec8","tarball":"https://registry.npmjs.org/@bun-win32/propsys/-/propsys-2.0.0.tgz","fileCount":6,"integrity":"sha512-hTGk5jBWntUvh7OOL6gRoAU+zA2ZTTsd9btsJ7vrnz14WhM8RHIkzk5o3i4V59/mXZ4++pPW1nHsGQjG4TF63Q==","signatures":[{"sig":"MEQCIEifVfhEm0vO5VaOmp+OK42o1mNhhgqcalE1yn+0j/FoAiB4Djmn6aIQs8ysVWXuLbnXBLFgEU5sJQxhl8OZuKO56w==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":103121},"main":"./index.ts","type":"module","module":"index.ts","shasum":"bd416bf466525e6ccf10466f2dc5ea30ed718ec8","engines":{"bun":">=1.1.0"},"exports":{".":"./index.ts"},"private":false,"scripts":{"example:windows-sort-visualizer":"bun ./example/windows-sort-visualizer.ts","example:property-system-diagnostic":"bun ./example/property-system-diagnostic.ts"},"_npmUser":{"name":"obscuritysrl","email":"stev.p@outlook.com"},"_integrity":"sha512-hTGk5jBWntUvh7OOL6gRoAU+zA2ZTTsd9btsJ7vrnz14WhM8RHIkzk5o3i4V59/mXZ4++pPW1nHsGQjG4TF63Q==","repository":{"url":"git://github.com/ObscuritySRL/bun-win32.git","type":"git","directory":"packages/propsys"},"_npmVersion":"10.8.3","description":"Zero-dependency, zero-overhead Win32 PROPSYS bindings for Bun (FFI) on Windows.","directories":{},"sideEffects":false,"_nodeVersion":"26.3.0","dependencies":{"@bun-win32/core":"2.0.0"},"_hasShrinkwrap":false,"devDependencies":{"@types/bun":"latest"},"peerDependencies":{"typescript":"^5"},"_npmOperationalInternal":{"tmp":"tmp/propsys_2.0.0_1782435493933_0.053672948357650574","host":"s3://npm-registry-packages-npm-production"}},"2.0.1":{"author":"Stev Peifer <stev.p@outlook.com>","bugs":{"url":"https://github.com/ObscuritySRL/bun-win32/issues"},"dependencies":{"@bun-win32/core":"2.0.1"},"description":"Zero-dependency, zero-overhead Win32 PROPSYS bindings for Bun (FFI) on Windows.","devDependencies":{"@types/bun":"latest"},"exports":{".":"./index.ts"},"license":"MIT","module":"index.ts","name":"@bun-win32/propsys","peerDependencies":{"typescript":"^5"},"private":false,"homepage":"https://github.com/ObscuritySRL/bun-win32#readme","repository":{"type":"git","url":"git://github.com/ObscuritySRL/bun-win32.git","directory":"packages/propsys"},"type":"module","version":"2.0.1","main":"./index.ts","keywords":["bun","ffi","win32","windows","propsys","bindings","typescript","dll"],"sideEffects":false,"engines":{"bun":">=1.1.0"},"scripts":{"example:property-system-diagnostic":"bun ./example/property-system-diagnostic.ts","example:windows-sort-visualizer":"bun ./example/windows-sort-visualizer.ts"},"_id":"@bun-win32/propsys@2.0.1","_integrity":"sha512-O8ItVpWq60TSXl6UxnzO/OBr5DS2CnnbNxbNKV4M4sRLqmoO4neAHEBEs//8D74slgM9bk2y5yTdgE972npH4w==","_nodeVersion":"26.3.0","_npmVersion":"10.8.3","shasum":"09ed67cfebe618faeeec0e807332b1107187b340","dist":{"integrity":"sha512-O8ItVpWq60TSXl6UxnzO/OBr5DS2CnnbNxbNKV4M4sRLqmoO4neAHEBEs//8D74slgM9bk2y5yTdgE972npH4w==","shasum":"09ed67cfebe618faeeec0e807332b1107187b340","tarball":"https://registry.npmjs.org/@bun-win32/propsys/-/propsys-2.0.1.tgz","fileCount":6,"unpackedSize":103121,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQC0t47Ipm4rDDeWMPoOuVvruzruiXA9goFeOm2unRspfwIhAM2F+Axk9o6RQg3e8lnbOJ9kk8ivKZjX4L/X6If5MIkv"}]},"_npmUser":{"name":"obscuritysrl","email":"stev.p@outlook.com"},"directories":{},"maintainers":[{"name":"obscuritysrl","email":"stev.p@outlook.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/propsys_2.0.1_1782438154225_0.7225309526914823"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-18T02:56:53.208Z","modified":"2026-06-26T01:42:34.504Z","1.0.0":"2026-05-18T02:56:53.537Z","2.0.0":"2026-06-26T00:58:14.063Z","2.0.1":"2026-06-26T01:42:34.364Z"},"bugs":{"url":"https://github.com/ObscuritySRL/bun-win32/issues"},"author":"Stev Peifer <stev.p@outlook.com>","license":"MIT","homepage":"https://github.com/ObscuritySRL/bun-win32#readme","keywords":["bun","ffi","win32","windows","propsys","bindings","typescript","dll"],"repository":{"type":"git","url":"git://github.com/ObscuritySRL/bun-win32.git","directory":"packages/propsys"},"description":"Zero-dependency, zero-overhead Win32 PROPSYS bindings for Bun (FFI) on Windows.","maintainers":[{"name":"obscuritysrl","email":"stev.p@outlook.com"}],"readme":"# @bun-win32/propsys\r\n\r\nZero-dependency, zero-overhead Win32 Propsys bindings for [Bun](https://bun.sh) on Windows.\r\n\r\n## Overview\r\n\r\n`@bun-win32/propsys` exposes the `propsys.dll` exports using [Bun](https://bun.sh)'s FFI. It provides a single class, `Propsys`, which lazily binds native symbols on first use. You can optionally preload a subset or all symbols up-front via `Preload()`.\r\n\r\nThe bindings are strongly typed for a smooth DX in TypeScript.\r\n\r\n## Features\r\n\r\n- [Bun](https://bun.sh)-first ergonomics on Windows 10/11.\r\n- Direct FFI to `propsys.dll` (PROPVARIANT/VARIANT helpers, property keys, and property stores).\r\n- In-source docs in `structs/Propsys.ts` with links to Microsoft Docs.\r\n- Lazy binding on first call; optional eager preload (`Propsys.Preload()`).\r\n- No wrapper overhead; calls map 1:1 to native APIs.\r\n- Strongly-typed Win32 aliases (see `types/Propsys.ts`).\r\n\r\n## Requirements\r\n\r\n- [Bun](https://bun.sh) runtime\r\n- Windows 10 or later\r\n\r\n## Installation\r\n\r\n```sh\r\nbun add @bun-win32/propsys\r\n```\r\n\r\n## Quick Start\r\n\r\n```ts\r\nimport Propsys from '@bun-win32/propsys';\r\n\r\n// Resolve a canonical property name to its binary PROPERTYKEY\r\n// (GUID fmtid + DWORD pid = 20 bytes), then format it back to a string.\r\nconst name = Buffer.from('System.Title\\0', 'utf16le');\r\nconst key = Buffer.alloc(20);\r\n\r\nif (Propsys.PSGetPropertyKeyFromName(name.ptr, key.ptr) === 0) {\r\n  const text = Buffer.alloc(256 * 2); // wide chars\r\n  Propsys.PSStringFromPropertyKey(key.ptr, text.ptr, 256);\r\n  console.log(text.toString('utf16le').replace(/\\0.*$/, ''));\r\n  // {F29F85E0-4FF9-1068-AB91-08002B27B3D9} 2\r\n}\r\n```\r\n\r\n> [!NOTE]\r\n> `PSGetPropertyKeyFromName` resolves names through the COM-based property\r\n> schema, so call `CoInitialize`/`CoInitializeEx` on the thread first. The\r\n> `PropVariant*`/`Variant*` value helpers and `PropVariantCompareEx` do not\r\n> require COM.\r\n\r\n> [!NOTE]\r\n> AI agents: see `AI.md` for the package binding contract and source-navigation guidance. It explains how to use the package without scanning the entire implementation.\r\n\r\n## Examples\r\n\r\nRun the included examples:\r\n\r\n```sh\r\n# Thorough diagnostic: property-key dictionary + PROPVARIANT conversion matrix\r\nbun run example/property-system-diagnostic.ts\r\n\r\n# Animated: a deck sorted live by Windows' own PropVariantCompareEx, three ways\r\nbun run example/windows-sort-visualizer.ts\r\n```\r\n\r\n## Notes\r\n\r\n- Either rely on lazy binding or call `Propsys.Preload()`.\r\n- Windows only. Bun runtime required.\n- **SAL types & naming:** nullability is in the **type** — `Optional<T>` (formally optional, SAL `_*opt_`) and `Nullable<T>` (plain `[in]`/`[out]` the docs say can be NULL), the null sentinel derived from `T` (`null` for pointers `LP*`/`P*`, `0n` for handles/by-value addresses); direction is in the **parameter name** — `_out` (`_Out_`), `_in_out` (`_Inout_`), `_In_` bare. See `AI.md` and the repo `AGENTS.md`.\n","readmeFilename":"README.md"}