@bun-win32/core 1.0.1

package/README.md

@@ -0,0 +1,64 @@
+# @bun-win32/core
+
+Shared base class, runtime extensions, and fundamental Win32 types for `@bun-win32` packages.
+
+## Overview
+
+`@bun-win32/core` provides the foundation that all `@bun-win32` DLL packages build on:
+
+- **`Win32` base class** — Abstract class that handles lazy `dlopen` loading and symbol memoization. Every DLL package (`kernel32`, `user32`, etc.) extends this class.
+- **Runtime extensions** — Installs a `.ptr` getter on all `ArrayBuffer`, `Buffer`, `DataView`, and typed array prototypes, giving direct access to native pointers for Bun FFI calls.
+- **Win32 type aliases** — Strongly-typed aliases (`HANDLE`, `DWORD`, `LPVOID`, `BOOL`, etc.) that map Win32 C types to their TypeScript equivalents.
+
+## Requirements
+
+- [Bun](https://bun.sh) runtime
+- Windows 10 or later
+
+## Installation
+
+```sh
+bun add @bun-win32/core
+```
+
+> You typically do not need to install this directly — it is pulled in as a dependency of each DLL package.
+
+## Usage
+
+### Extending `Win32` for a new DLL
+
+```ts
+import { FFIType, type FFIFunction } from 'bun:ffi';
+import { Win32 } from '@bun-win32/core';
+
+class MyDll extends Win32 {
+  protected static override name = 'mydll.dll';
+  protected static override readonly Symbols = {
+    MyFunction: { args: [FFIType.u32], returns: FFIType.i32 },
+  } as const satisfies Record<string, FFIFunction>;
+
+  public static MyFunction(value: number): number {
+    return MyDll.Load('MyFunction')(value);
+  }
+}
+```
+
+### Runtime pointer extensions
+
+```ts
+import '@bun-win32/core';
+
+const buffer = new Uint8Array([1, 2, 3]);
+nativeFunction(buffer.ptr, buffer.length);
+```
+
+### Win32 type aliases
+
+```ts
+import type { DWORD, HANDLE, BOOL } from '@bun-win32/core';
+```
+
+## Notes
+
+- This package is a dependency of all `@bun-win32` DLL packages.
+- Windows only. Bun runtime required.

package/index.ts

@@ -0,0 +1,6 @@
+import './runtime/extensions';
+
+import { Win32 } from './structs/Win32';
+
+export * from './types/Win32';
+export { Win32 };

package/package.json

@@ -0,0 +1,50 @@
+{
+  "author": "Stev Peifer <stev@bell.net>",
+  "description": "Shared base class, runtime extensions, and fundamental Win32 types for @bun-win32 packages.",
+  "devDependencies": {
+    "@types/bun": "latest"
+  },
+  "exports": {
+    ".": "./index.ts"
+  },
+  "license": "MIT",
+  "module": "index.ts",
+  "name": "@bun-win32/core",
+  "peerDependencies": {
+    "typescript": "^5"
+  },
+  "private": false,
+  "bugs": {
+    "url": "https://github.com/ObscuritySRL/bun-win32/issues"
+  },
+  "homepage": "https://github.com/ObscuritySRL/bun-win32#readme",
+  "repository": {
+    "type": "git",
+    "url": "git://github.com/ObscuritySRL/bun-win32.git",
+    "directory": "packages/core"
+  },
+  "type": "module",
+  "version": "1.0.1",
+  "main": "./index.ts",
+  "keywords": [
+    "bun",
+    "ffi",
+    "win32",
+    "windows",
+    "bindings",
+    "typescript",
+    "dll",
+    "core"
+  ],
+  "files": [
+    "index.ts",
+    "runtime/*.ts",
+    "structs/*.ts",
+    "types/*.ts",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "bun": ">=1.1.0"
+  }
+}

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 {};

package/structs/Win32.ts

@@ -0,0 +1,78 @@
+import { type FFIFunction, dlopen } from 'bun:ffi';
+
+/**
+ * Abstract base class for lazy-loaded Win32 DLL FFI bindings.
+ *
+ * Subclasses set `name` and `Symbols`, then call `Load` in their public
+ * methods to bind individual exports on first use. For bulk, up-front binding
+ * use `Preload`.
+ *
+ * @example
+ * ```ts
+ * class Kernel32 extends Win32 {
+ *   protected static override name = 'kernel32.dll';
+ *   protected static override readonly Symbols = {
+ *     GetTickCount64: { args: [], returns: FFIType.u64 },
+ *   } as const satisfies Record<string, FFIFunction>;
+ *
+ *   public static GetTickCount64(): bigint {
+ *     return Kernel32.Load('GetTickCount64')();
+ *   }
+ * }
+ * ```
+ */
+export class Win32 {
+  protected static readonly Symbols: Record<string, FFIFunction> = {};
+  protected static name: string;
+
+  /**
+   * Lazily binds a single DLL export and memoizes it on the subclass.
+   *
+   * If the symbol has already been bound (property is non-configurable), this is a no-op.
+   * Subsequent calls go directly through the memoized native function.
+   *
+   * @param method Exact export name from `Symbols`.
+   * @returns The bound native function.
+   */
+  protected static Load(method: string) {
+    if (Object.getOwnPropertyDescriptor(this, method)?.configurable === false) {
+      return (this as any)[method];
+    }
+
+    const library = dlopen(this.name, { [method]: this.Symbols[method]! });
+    const propertyDescriptor = {
+      configurable: false,
+      value: library.symbols[method],
+    };
+
+    Object.defineProperty(this, method, propertyDescriptor);
+
+    return (this as any)[method];
+  }
+
+  /**
+   * Eagerly binds multiple DLL exports at once.
+   *
+   * Pass a subset of method names to bind only what you need for hot paths; when omitted,
+   * all symbols declared in `Symbols` are bound. Already-bound symbols are skipped.
+   *
+   * @param methods Optional list of export names to bind.
+   */
+  public static Preload(methods?: string[]): void {
+    methods ??= Object.keys(this.Symbols);
+
+    const symbols = Object.fromEntries(
+      methods.filter((method) => Object.getOwnPropertyDescriptor(this, method)?.configurable !== false).map((method) => [method, this.Symbols[method]!]), //
+    );
+
+    const library = dlopen(this.name, symbols);
+
+    const propertyDescriptorMap = Object.fromEntries(
+      Object.entries(library.symbols).map(([key, value]) => [key, { configurable: false, value }]), //
+    );
+
+    Object.defineProperties(this, propertyDescriptorMap);
+
+    return;
+  }
+}

package/types/Win32.ts

@@ -0,0 +1,62 @@
+import type { Pointer } from 'bun:ffi';
+
+// ── Scalar types (number) ───────────────────────────────────────────────────
+
+export type ACCESS_MASK = number;
+export type BOOL = number;
+export type BOOLEAN = number;
+export type BYTE = number;
+export type CHAR = number;
+export type DWORD = number;
+export type HRESULT = LONG;
+export type INT = number;
+export type LONG = number;
+export type SHORT = number;
+export type UINT = number;
+export type ULONG = number;
+export type USHORT = number;
+export type WCHAR = number;
+export type WORD = number;
+
+// ── 64-bit types (bigint) ───────────────────────────────────────────────────
+
+export type DWORD_PTR = bigint;
+export type HANDLE = bigint;
+export type HINSTANCE = bigint;
+export type HMODULE = bigint;
+export type HWND = bigint;
+export type INT_PTR = bigint;
+export type LONG_PTR = bigint;
+export type SIZE_T = bigint;
+export type UINT_PTR = bigint;
+export type ULONG_PTR = bigint;
+
+// ── Derived types ───────────────────────────────────────────────────────────
+
+export type LPARAM = LONG_PTR;
+export type LRESULT = LONG_PTR;
+export type WPARAM = UINT_PTR;
+
+// ── Common pointer types ────────────────────────────────────────────────────
+
+export type LPBOOL = Pointer;
+export type LPBYTE = Pointer;
+export type LPCSTR = Pointer;
+export type LPCVOID = Pointer;
+export type LPCWSTR = Pointer;
+export type LPDWORD = Pointer;
+export type LPHANDLE = Pointer;
+export type LPSECURITY_ATTRIBUTES = Pointer;
+export type LPSTR = Pointer;
+export type LPVOID = Pointer;
+export type LPWSTR = Pointer;
+export type PBYTE = Pointer;
+export type PDWORD = Pointer;
+export type PHANDLE = Pointer;
+export type PULONG = Pointer;
+export type PVOID = Pointer;
+
+// ── Special ─────────────────────────────────────────────────────────────────
+
+export type NULL = null;
+export type VOID = void;