@bun-win32/propsys 1.0.0

package/AI.md

@@ -0,0 +1,71 @@
+# AI Guide for @bun-win32/propsys
+
+How to use this package, not what the Win32 API does.
+
+## Usage
+
+```ts
+import Propsys, { SomeFlag } from '@bun-win32/propsys';
+
+// Methods bind lazily on first call
+const result = Propsys.SomeFunctionW(arg1, arg2);
+
+// Preload: array, single string, or no args (all symbols)
+Propsys.Preload(['SomeFunctionW', 'AnotherFunction']);
+Propsys.Preload('SomeFunctionW');
+Propsys.Preload();
+```
+
+## Where To Look
+
+| Need                              | Read                 |
+| --------------------------------- | -------------------- |
+| Find a method or its MS Docs link | `structs/Propsys.ts` |
+| Find types, enums, constants      | `types/Propsys.ts`   |
+| Quick examples                    | `README.md`          |
+
+`index.ts` re-exports the class and all types — import from `@bun-win32/propsys` directly.
+
+## Calling Convention
+
+All documented `propsys.dll` exports are bound. Each method maps 1:1 to its DLL export. Names, parameter names, and order match Microsoft Docs.
+
+### Strings
+
+`W` methods take UTF-16LE NUL-terminated buffers. `A` methods take ANSI strings.
+
+```ts
+const wide = Buffer.from('Hello\0', 'utf16le');  // LPCWSTR
+Propsys.SomeFunctionW(wide.ptr);
+
+// Reading a wide string back from a buffer:
+const text = new TextDecoder('utf-16').decode(buf).replace(/\0.*$/, '');
+```
+
+### Return types
+
+- `HANDLE`, `HWND`, etc. → `bigint`
+- `DWORD`, `UINT`, `BOOL`, `INT`, `LONG` → `number`
+- `LPVOID`, `LPWSTR`, etc. → `Pointer`
+- Win32 `BOOL` is `number` (0 or non-zero), **not** JS `boolean`. Do not compare with `=== true`.
+
+### Pointers, handles, out-parameters
+
+- **Pointer** params (`LP*`, `P*`, `Pointer`): pass `buffer.ptr` from a caller-allocated `Buffer`.
+- **Handle** params (`HANDLE`, `HWND`, etc.): pass a `bigint` value.
+- **Out-parameters**: allocate a `Buffer`, pass `.ptr`, read the result after the call.
+
+```ts
+const out = Buffer.alloc(4);
+Propsys.SomeFunction(out.ptr);
+const value = out.readUInt32LE(0);
+```
+
+### Nullability
+
+- `| NULL` in a signature → pass `null` (optional pointer).
+- `| 0n` in a signature → pass `0n` (optional handle).
+
+## Errors and Cleanup
+
+Return values are raw. If the Win32 function uses last-error semantics, read via `GetLastError()`. Resource cleanup is your responsibility — same as raw Win32.

package/README.md

@@ -0,0 +1,73 @@
+# @bun-win32/propsys
+
+Zero-dependency, zero-overhead Win32 Propsys bindings for [Bun](https://bun.sh) on Windows.
+
+## Overview
+
+`@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()`.
+
+The bindings are strongly typed for a smooth DX in TypeScript.
+
+## Features
+
+- [Bun](https://bun.sh)-first ergonomics on Windows 10/11.
+- Direct FFI to `propsys.dll` (PROPVARIANT/VARIANT helpers, property keys, and property stores).
+- In-source docs in `structs/Propsys.ts` with links to Microsoft Docs.
+- Lazy binding on first call; optional eager preload (`Propsys.Preload()`).
+- No wrapper overhead; calls map 1:1 to native APIs.
+- Strongly-typed Win32 aliases (see `types/Propsys.ts`).
+
+## Requirements
+
+- [Bun](https://bun.sh) runtime
+- Windows 10 or later
+
+## Installation
+
+```sh
+bun add @bun-win32/propsys
+```
+
+## Quick Start
+
+```ts
+import Propsys from '@bun-win32/propsys';
+
+// Resolve a canonical property name to its binary PROPERTYKEY
+// (GUID fmtid + DWORD pid = 20 bytes), then format it back to a string.
+const name = Buffer.from('System.Title\0', 'utf16le');
+const key = Buffer.alloc(20);
+
+if (Propsys.PSGetPropertyKeyFromName(name.ptr, key.ptr) === 0) {
+  const text = Buffer.alloc(256 * 2); // wide chars
+  Propsys.PSStringFromPropertyKey(key.ptr, text.ptr, 256);
+  console.log(text.toString('utf16le').replace(/\0.*$/, ''));
+  // {F29F85E0-4FF9-1068-AB91-08002B27B3D9} 2
+}
+```
+
+> [!NOTE]
+> `PSGetPropertyKeyFromName` resolves names through the COM-based property
+> schema, so call `CoInitialize`/`CoInitializeEx` on the thread first. The
+> `PropVariant*`/`Variant*` value helpers and `PropVariantCompareEx` do not
+> require COM.
+
+> [!NOTE]
+> 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.
+
+## Examples
+
+Run the included examples:
+
+```sh
+# Thorough diagnostic: property-key dictionary + PROPVARIANT conversion matrix
+bun run example/property-system-diagnostic.ts
+
+# Animated: a deck sorted live by Windows' own PropVariantCompareEx, three ways
+bun run example/windows-sort-visualizer.ts
+```
+
+## Notes
+
+- Either rely on lazy binding or call `Propsys.Preload()`.
+- Windows only. Bun runtime required.

package/index.ts

@@ -0,0 +1,4 @@
+import Propsys from './structs/Propsys';
+
+export * from './types/Propsys';
+export default Propsys;

package/package.json

@@ -0,0 +1,57 @@
+{
+  "author": "Stev Peifer <stev@bell.net>",
+  "bugs": {
+    "url": "https://github.com/ObscuritySRL/bun-win32/issues"
+  },
+  "dependencies": {
+    "@bun-win32/core": "1.1.2"
+  },
+  "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": "1.0.0",
+  "main": "./index.ts",
+  "keywords": [
+    "bun",
+    "ffi",
+    "win32",
+    "windows",
+    "propsys",
+    "bindings",
+    "typescript",
+    "dll"
+  ],
+  "files": [
+    "AI.md",
+    "README.md",
+    "index.ts",
+    "structs/*.ts",
+    "types/*.ts"
+  ],
+  "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"
+  }
+}