@bun-win32/shell32 1.0.0

package/README.md

@@ -0,0 +1,60 @@
+# @bun-win32/shell32
+
+Zero-dependency, zero-overhead Win32 SHELL32 bindings for [Bun](https://bun.sh) on Windows.
+
+## Overview
+
+`@bun-win32/shell32` exposes the `shell32.dll` exports using [Bun](https://bun.sh)'s FFI. It provides a single class, `Shell32`, 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 `shell32.dll` (~250 bindings covering shell operations, file management, notifications, drag-and-drop, and more).
+- In-source docs in `structs/Shell32.ts` with links to Microsoft Docs.
+- Lazy binding on first call; optional eager preload (`Shell32.Preload()`).
+- No wrapper overhead; calls map 1:1 to native APIs.
+- Strongly-typed Win32 aliases (see `types/Shell32.ts`).
+
+## Requirements
+
+- [Bun](https://bun.sh) runtime
+- Windows 10 or later
+
+## Installation
+
+```sh
+bun add @bun-win32/shell32
+```
+
+## Quick Start
+
+```ts
+import Shell32 from '@bun-win32/shell32';
+
+// Optionally bind a subset up-front
+Shell32.Preload(['SHGetFolderPathW', 'IsUserAnAdmin', 'CommandLineToArgvW']);
+
+// Check admin status
+const isAdmin = Shell32.IsUserAnAdmin();
+console.log('Admin:', !!isAdmin);
+
+// Get APPDATA path (CSIDL_APPDATA = 0x001A)
+const pathBuf = Buffer.alloc(520);
+Shell32.SHGetFolderPathW(0n, 0x001a, 0n, 0, pathBuf.ptr);
+console.log('APPDATA:', pathBuf.toString('utf16le').replace(/\0+$/, ''));
+```
+
+## Examples
+
+Run the included example:
+
+```sh
+bun run example              # Admin check, folder paths, command-line parsing, recycle bin info
+```
+
+## Notes
+
+- Either rely on lazy binding or call `Shell32.Preload()`.
+- Windows only. Bun runtime required.

package/index.ts

@@ -0,0 +1,6 @@
+import './runtime/extensions';
+
+import Shell32 from './structs/Shell32';
+
+export * from './types/Shell32';
+export default Shell32;

package/package.json

@@ -0,0 +1,52 @@
+{
+  "author": "Stev Peifer <stev@bell.net>",
+  "bugs": {
+    "url": "https://github.com/bun-win32/shell32/issues"
+  },
+  "description": "Zero-dependency, zero-overhead Win32 SHELL32 bindings for Bun (FFI) on Windows.",
+  "devDependencies": {
+    "@types/bun": "latest"
+  },
+  "exports": {
+    ".": "./index.ts"
+  },
+  "license": "MIT",
+  "module": "index.ts",
+  "name": "@bun-win32/shell32",
+  "peerDependencies": {
+    "typescript": "^5"
+  },
+  "private": false,
+  "homepage": "https://github.com/bun-win32/shell32#readme",
+  "repository": {
+    "type": "git",
+    "url": "git://github.com/bun-win32/shell32.git"
+  },
+  "type": "module",
+  "version": "1.0.0",
+  "main": "./index.ts",
+  "keywords": [
+    "bun",
+    "ffi",
+    "win32",
+    "windows",
+    "shell32",
+    "bindings",
+    "typescript",
+    "dll"
+  ],
+  "files": [
+    "index.ts",
+    "runtime/*.ts",
+    "structs/*.ts",
+    "types/*.ts",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "bun": ">=1.1.0"
+  },
+  "scripts": {
+    "example": "bun ./example/shell32.ts"
+  }
+}

package/runtime/extensions.ts

@@ -0,0 +1,210 @@
+import { type Pointer, ptr } from 'bun:ffi';
+
+declare global {
+  /**
+   * Adds a native pointer property to all ArrayBuffer, Buffer, DataView, and TypedArray types.
+   *
+   * The `ptr` property returns a native pointer usable with Bun FFI.
+   *
+   * @example
+   * ```ts
+   * const arr = new Uint8Array([1, 2, 3]);
+   * nativeFunction(arr.ptr, arr.length);
+   * ```
+   */
+  interface ArrayBuffer {
+    /**
+     * Native pointer to ArrayBuffer memory for Bun FFI.
+     * @example
+     * ```ts
+     * const buf = new ArrayBuffer(8);
+     * nativeFunction(buf.ptr, buf.byteLength);
+     * ```
+     */
+    readonly ptr: Pointer;
+  }
+  interface BigInt64Array {
+    /**
+     * Native pointer to BigInt64Array memory for Bun FFI.
+     * @example
+     * ```ts
+     * const arr = new BigInt64Array([1n, 2n]);
+     * nativeFunction(arr.ptr, arr.length);
+     * ```
+     */
+    readonly ptr: Pointer;
+  }
+  interface BigUint64Array {
+    /**
+     * Native pointer to BigUint64Array memory for Bun FFI.
+     * @example
+     * ```ts
+     * const arr = new BigUint64Array([1n, 2n]);
+     * nativeFunction(arr.ptr, arr.length);
+     * ```
+     */
+    readonly ptr: Pointer;
+  }
+  interface Buffer {
+    /**
+     * Native pointer to Buffer memory for Bun FFI.
+     * @example
+     * ```ts
+     * const buf = Buffer.from([1, 2, 3]);
+     * nativeFunction(buf.ptr, buf.length);
+     * ```
+     */
+    readonly ptr: Pointer;
+  }
+  interface DataView {
+    /**
+     * Native pointer to DataView memory for Bun FFI.
+     * @example
+     * ```ts
+     * const view = new DataView(new ArrayBuffer(4));
+     * nativeFunction(view.ptr, view.byteLength);
+     * ```
+     */
+    readonly ptr: Pointer;
+  }
+  interface Float32Array {
+    /**
+     * Native pointer to Float32Array memory for Bun FFI.
+     * @example
+     * ```ts
+     * const arr = new Float32Array([1, 2, 3]);
+     * nativeFunction(arr.ptr, arr.length);
+     * ```
+     */
+    readonly ptr: Pointer;
+  }
+  interface Float64Array {
+    /**
+     * Native pointer to Float64Array memory for Bun FFI.
+     * @example
+     * ```ts
+     * const arr = new Float64Array([1, 2, 3]);
+     * nativeFunction(arr.ptr, arr.length);
+     * ```
+     */
+    readonly ptr: Pointer;
+  }
+  interface Int16Array {
+    /**
+     * Native pointer to Int16Array memory for Bun FFI.
+     * @example
+     * ```ts
+     * const arr = new Int16Array([1, 2, 3]);
+     * nativeFunction(arr.ptr, arr.length);
+     * ```
+     */
+    readonly ptr: Pointer;
+  }
+  interface Int32Array {
+    /**
+     * Native pointer to Int32Array memory for Bun FFI.
+     * @example
+     * ```ts
+     * const arr = new Int32Array([1, 2, 3]);
+     * nativeFunction(arr.ptr, arr.length);
+     * ```
+     */
+    readonly ptr: Pointer;
+  }
+  interface Int8Array {
+    /**
+     * Native pointer to Int8Array memory for Bun FFI.
+     * @example
+     * ```ts
+     * const arr = new Int8Array([1, 2, 3]);
+     * nativeFunction(arr.ptr, arr.length);
+     * ```
+     */
+    readonly ptr: Pointer;
+  }
+  interface SharedArrayBuffer {
+    /**
+     * Native pointer to SharedArrayBuffer memory for Bun FFI.
+     * @example
+     * ```ts
+     * const buf = new SharedArrayBuffer(8);
+     * nativeFunction(buf.ptr, buf.byteLength);
+     * ```
+     */
+    readonly ptr: Pointer;
+  }
+  interface Uint16Array {
+    /**
+     * Native pointer to Uint16Array memory for Bun FFI.
+     * @example
+     * ```ts
+     * const arr = new Uint16Array([1, 2, 3]);
+     * nativeFunction(arr.ptr, arr.length);
+     * ```
+     */
+    readonly ptr: Pointer;
+  }
+  interface Uint32Array {
+    /**
+     * Native pointer to Uint32Array memory for Bun FFI.
+     * @example
+     * ```ts
+     * const arr = new Uint32Array([1, 2, 3]);
+     * nativeFunction(arr.ptr, arr.length);
+     * ```
+     */
+    readonly ptr: Pointer;
+  }
+  interface Uint8Array {
+    /**
+     * Native pointer to Uint8Array memory for Bun FFI.
+     * @example
+     * ```ts
+     * const arr = new Uint8Array([1, 2, 3]);
+     * nativeFunction(arr.ptr, arr.length);
+     * ```
+     */
+    readonly ptr: Pointer;
+  }
+  interface Uint8ClampedArray {
+    /**
+     * Native pointer to Uint8ClampedArray memory for Bun FFI.
+     * @example
+     * ```ts
+     * const arr = new Uint8ClampedArray([1, 2, 3]);
+     * nativeFunction(arr.ptr, arr.length);
+     * ```
+     */
+    readonly ptr: Pointer;
+  }
+}
+
+/**
+ * Installs the `ptr` property on all supported binary view prototypes.
+ *
+ * The property is non-enumerable and non-configurable. The getter calls `ptr(this)`.
+ */
+const constructors = [ArrayBuffer, BigInt64Array, BigUint64Array, Buffer, DataView, Float32Array, Float64Array, Int16Array, Int32Array, Int8Array, SharedArrayBuffer, Uint16Array, Uint32Array, Uint8Array, Uint8ClampedArray] as const;
+
+constructors.forEach(
+  ({ prototype }) =>
+    !Object.getOwnPropertyDescriptor(prototype, 'ptr') &&
+    Object.defineProperty(prototype, 'ptr', {
+      configurable: false,
+      enumerable: false,
+      /**
+       * Returns a native pointer to the underlying memory.
+       * @returns Native pointer for Bun FFI.
+       * @example
+       * ```ts
+       * const arr = new Uint8Array([1, 2, 3]);
+       * nativeFunction(arr.ptr, arr.length);
+       * ```
+       */
+      get(this): Pointer {
+        return ptr(this);
+      },
+    })
+);
+
+export {};