objcjs-types 0.2.1 → 0.3.0

package/generator/parse-worker.ts

@@ -0,0 +1,263 @@
+/**
+ * Worker thread for parallel header parsing.
+ * Receives parse tasks via postMessage, runs clang AST dump + parsing,
+ * and returns parsed results to the main thread.
+ *
+ * Each worker handles one task at a time. The WorkerPool dispatches
+ * tasks to idle workers for automatic load balancing.
+ */
+
+declare var self: Worker;
+
+import { clangASTDump, clangASTDumpWithPreIncludes, clangBatchASTDump } from "./clang.ts";
+import {
+  parseAST,
+  parseProtocols,
+  parseIntegerEnums,
+  parseStringEnums,
+  parseStructs,
+  parseTypedefs,
+  parseFunctions
+} from "./ast-parser.ts";
+
+/**
+ * Read a header file and split it into lines for deprecation scanning.
+ */
+async function readHeaderLines(headerPath: string): Promise<string[] | undefined> {
+  try {
+    const content = await Bun.file(headerPath).text();
+    return content.split("\n");
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Read multiple header files and build a map of file path → lines
+ * for batched deprecation scanning.
+ */
+async function readHeaderLinesMap(headerPaths: string[]): Promise<Map<string, string[]>> {
+  const map = new Map<string, string[]>();
+  const results = await Promise.all(
+    headerPaths.map(async (p) => {
+      try {
+        const content = await Bun.file(p).text();
+        return { path: p, lines: content.split("\n") };
+      } catch {
+        return { path: p, lines: undefined };
+      }
+    })
+  );
+  for (const { path, lines } of results) {
+    if (lines) map.set(path, lines);
+  }
+  return map;
+}
+
+self.onmessage = async (event: MessageEvent) => {
+  const msg = event.data;
+
+  try {
+    if (msg.type === "parse-batch") {
+      // Batched framework task: parse all classes, protocols, and enums from
+      // a single clang invocation that includes ALL framework headers at once.
+      // This dramatically reduces clang process overhead.
+      const classTargetSet = new Set<string>(msg.classTargets ?? []);
+      const protocolTargetSet = new Set<string>(msg.protocolTargets ?? []);
+      const integerTargetSet = new Set<string>(msg.integerEnumTargets ?? []);
+      const stringTargetSet = new Set<string>(msg.stringEnumTargets ?? []);
+      const headerPaths: string[] = msg.headerPaths ?? [];
+      const preIncludes: string[] = msg.preIncludes ?? [];
+
+      // Read all header files for deprecation scanning concurrently with clang.
+      const [headerLinesMap, ast] = await Promise.all([
+        readHeaderLinesMap(headerPaths),
+        clangBatchASTDump(headerPaths, preIncludes)
+      ]);
+
+      const classes = classTargetSet.size > 0 ? parseAST(ast, classTargetSet, undefined, headerLinesMap) : new Map();
+      const protocols =
+        protocolTargetSet.size > 0 ? parseProtocols(ast, protocolTargetSet, undefined, headerLinesMap) : new Map();
+      const integerEnums = integerTargetSet.size > 0 ? parseIntegerEnums(ast, integerTargetSet) : new Map();
+      const stringEnums = stringTargetSet.size > 0 ? parseStringEnums(ast, stringTargetSet) : new Map();
+      const structResult = parseStructs(ast);
+      const typedefs = parseTypedefs(ast);
+
+      // Parse C function declarations from this framework's headers
+      const frameworkHeaderPathSet = new Set<string>(headerPaths);
+      const functions = parseFunctions(ast, frameworkHeaderPathSet, msg.frameworkName ?? "");
+
+      postMessage({
+        id: msg.id,
+        type: "batch-result",
+        classes: [...classes.entries()],
+        protocols: [...protocols.entries()],
+        integerEnums: [...integerEnums.entries()],
+        stringEnums: [...stringEnums.entries()],
+        structs: [...structResult.structs.entries()],
+        structAliases: structResult.aliases,
+        typedefs: [...typedefs.entries()],
+        functions: [...functions.entries()],
+        // Report what was found vs expected for logging
+        foundClasses: classes.size,
+        foundProtocols: protocols.size,
+        foundIntegerEnums: integerEnums.size,
+        foundStringEnums: stringEnums.size
+      });
+    } else if (msg.type === "parse-all") {
+      // Unified task: parse classes, protocols, and enums from a single clang AST.
+      // This avoids running clang multiple times on the same header file.
+      const classTargetSet = new Set<string>(msg.classTargets ?? []);
+      const protocolTargetSet = new Set<string>(msg.protocolTargets ?? []);
+      const integerTargetSet = new Set<string>(msg.integerEnumTargets ?? []);
+      const stringTargetSet = new Set<string>(msg.stringEnumTargets ?? []);
+
+      const headerLines = await readHeaderLines(msg.headerPath);
+      let ast = await clangASTDump(msg.headerPath);
+
+      let classes = classTargetSet.size > 0 ? parseAST(ast, classTargetSet, headerLines) : new Map();
+      let protocols = protocolTargetSet.size > 0 ? parseProtocols(ast, protocolTargetSet, headerLines) : new Map();
+      let integerEnums = integerTargetSet.size > 0 ? parseIntegerEnums(ast, integerTargetSet) : new Map();
+      let stringEnums = stringTargetSet.size > 0 ? parseStringEnums(ast, stringTargetSet) : new Map();
+      let structResult = parseStructs(ast);
+      let typedefs = parseTypedefs(ast);
+
+      // Fallback: retry without -fmodules using pre-includes if any expected
+      // target type has missing results. Some headers contain both classes and
+      // enums, where the class parses fine with -fmodules but the enum does not.
+      // The old all-or-nothing check would skip the fallback if any target type
+      // succeeded, causing enums (or other types) to be silently dropped.
+      const missingClasses = classTargetSet.size > 0 && classes.size < classTargetSet.size;
+      const missingProtocols = protocolTargetSet.size > 0 && protocols.size < protocolTargetSet.size;
+      const missingIntEnums = integerTargetSet.size > 0 && integerEnums.size < integerTargetSet.size;
+      const missingStrEnums = stringTargetSet.size > 0 && stringEnums.size < stringTargetSet.size;
+      const hasMissing = missingClasses || missingProtocols || missingIntEnums || missingStrEnums;
+
+      if (hasMissing && msg.fallbackPreIncludes) {
+        const fallbackAst = await clangASTDumpWithPreIncludes(msg.headerPath, msg.fallbackPreIncludes);
+
+        // Merge fallback results: only fill in targets that were missing from the
+        // primary parse. Keep primary results where they succeeded to avoid
+        // losing data that only -fmodules can provide.
+        if (missingClasses) {
+          const fallbackClasses = parseAST(fallbackAst, classTargetSet, headerLines);
+          for (const [name, cls] of fallbackClasses) {
+            if (!classes.has(name)) classes.set(name, cls);
+          }
+        }
+        if (missingProtocols) {
+          const fallbackProtocols = parseProtocols(fallbackAst, protocolTargetSet, headerLines);
+          for (const [name, proto] of fallbackProtocols) {
+            if (!protocols.has(name)) protocols.set(name, proto);
+          }
+        }
+        if (missingIntEnums) {
+          const fallbackIntEnums = parseIntegerEnums(fallbackAst, integerTargetSet);
+          for (const [name, enumDef] of fallbackIntEnums) {
+            if (!integerEnums.has(name)) integerEnums.set(name, enumDef);
+          }
+        }
+        if (missingStrEnums) {
+          const fallbackStrEnums = parseStringEnums(fallbackAst, stringTargetSet);
+          for (const [name, enumDef] of fallbackStrEnums) {
+            if (!stringEnums.has(name)) stringEnums.set(name, enumDef);
+          }
+        }
+        // Re-parse structs from fallback AST and merge
+        const fallbackStructResult = parseStructs(fallbackAst);
+        for (const [name, structDef] of fallbackStructResult.structs) {
+          if (!structResult.structs.has(name)) structResult.structs.set(name, structDef);
+        }
+        for (const alias of fallbackStructResult.aliases) {
+          if (!structResult.aliases.some((a) => a.name === alias.name)) {
+            structResult.aliases.push(alias);
+          }
+        }
+        // Merge fallback typedefs
+        const fallbackTypedefs = parseTypedefs(fallbackAst);
+        for (const [name, qualType] of fallbackTypedefs) {
+          if (!typedefs.has(name)) typedefs.set(name, qualType);
+        }
+      }
+
+      postMessage({
+        id: msg.id,
+        type: "all-result",
+        classes: [...classes.entries()],
+        protocols: [...protocols.entries()],
+        integerEnums: [...integerEnums.entries()],
+        stringEnums: [...stringEnums.entries()],
+        structs: [...structResult.structs.entries()],
+        structAliases: structResult.aliases,
+        typedefs: [...typedefs.entries()],
+        functions: [] // parse-all is used for extra headers which don't need function parsing
+      });
+    } else if (msg.type === "parse-classes") {
+      const targetSet = new Set<string>(msg.targets);
+      const headerLines = await readHeaderLines(msg.headerPath);
+      let ast = await clangASTDump(msg.headerPath);
+      let parsed = parseAST(ast, targetSet, headerLines);
+
+      // Fallback: retry without -fmodules using pre-includes.
+      // Some headers (e.g., WebKit) need Foundation macros pre-loaded.
+      if (parsed.size === 0 && msg.fallbackPreIncludes) {
+        ast = await clangASTDumpWithPreIncludes(msg.headerPath, msg.fallbackPreIncludes);
+        parsed = parseAST(ast, targetSet, headerLines);
+      }
+
+      postMessage({
+        id: msg.id,
+        type: "classes-result",
+        // Convert Map to entries array for structured clone fast path
+        classes: [...parsed.entries()],
+        targets: msg.targets
+      });
+    } else if (msg.type === "parse-protocols") {
+      const targetSet = new Set<string>(msg.targets);
+      const headerLines = await readHeaderLines(msg.headerPath);
+      let ast = await clangASTDump(msg.headerPath);
+      let parsed = parseProtocols(ast, targetSet, headerLines);
+
+      // Fallback
+      if (parsed.size === 0 && msg.fallbackPreIncludes) {
+        ast = await clangASTDumpWithPreIncludes(msg.headerPath, msg.fallbackPreIncludes);
+        parsed = parseProtocols(ast, targetSet, headerLines);
+      }
+
+      postMessage({
+        id: msg.id,
+        type: "protocols-result",
+        protocols: [...parsed.entries()],
+        targets: msg.targets
+      });
+    } else if (msg.type === "parse-enums") {
+      const integerTargetSet = new Set<string>(msg.integerTargets ?? []);
+      const stringTargetSet = new Set<string>(msg.stringTargets ?? []);
+      let ast = await clangASTDump(msg.headerPath);
+      let integerEnums = parseIntegerEnums(ast, integerTargetSet);
+      let stringEnums = parseStringEnums(ast, stringTargetSet);
+
+      // Fallback: retry without -fmodules using pre-includes
+      if (integerEnums.size === 0 && stringEnums.size === 0 && msg.fallbackPreIncludes) {
+        ast = await clangASTDumpWithPreIncludes(msg.headerPath, msg.fallbackPreIncludes);
+        integerEnums = parseIntegerEnums(ast, integerTargetSet);
+        stringEnums = parseStringEnums(ast, stringTargetSet);
+      }
+
+      postMessage({
+        id: msg.id,
+        type: "enums-result",
+        integerEnums: [...integerEnums.entries()],
+        stringEnums: [...stringEnums.entries()],
+        integerTargets: msg.integerTargets ?? [],
+        stringTargets: msg.stringTargets ?? []
+      });
+    }
+  } catch (error) {
+    postMessage({
+      id: msg.id,
+      type: "error",
+      error: String(error)
+    });
+  }
+};

package/generator/resolve-strings.ts

@@ -0,0 +1,121 @@
+/**
+ * Resolves extern NSString * constant values at generation time.
+ *
+ * String enums (NS_TYPED_EXTENSIBLE_ENUM) declare their values as extern
+ * NSString * constants in the framework binary. Since objc-js doesn't expose
+ * dlsym, we can't read these at runtime — but we CAN read them during
+ * generation using Bun's FFI to call dlopen/dlsym/objc_msgSend directly.
+ *
+ * This avoids compiling a helper binary (which fails on macOS Sequoia due to
+ * Gatekeeper blocking unsigned locally-compiled executables).
+ */
+
+import { dlopen as bunDlopen, FFIType, read, CString } from "bun:ffi";
+import type { Pointer } from "bun:ffi";
+
+/** Lazily initialized FFI bindings for dlopen/dlsym and ObjC runtime. */
+let ffi: {
+  dlopen: (path: Buffer, flags: number) => Pointer;
+  dlsym: (handle: Pointer, name: Buffer) => Pointer;
+  dlclose: (handle: Pointer) => number;
+  objc_msgSend: (obj: Pointer, sel: Pointer) => Pointer;
+  utf8Sel: Pointer;
+} | null = null;
+
+/** Convert a JS string to a null-terminated C string buffer. */
+function cstr(s: string): Buffer {
+  const buf = Buffer.alloc(s.length + 1);
+  buf.write(s, "utf-8");
+  return buf;
+}
+
+/** Initialize the FFI bindings once. */
+function ensureFFI() {
+  if (ffi) return ffi;
+
+  const libdl = bunDlopen("/usr/lib/libdl.dylib", {
+    dlopen: { args: [FFIType.ptr, FFIType.i32], returns: FFIType.ptr },
+    dlsym: { args: [FFIType.ptr, FFIType.ptr], returns: FFIType.ptr },
+    dlclose: { args: [FFIType.ptr], returns: FFIType.i32 }
+  });
+
+  const libobjc = bunDlopen("/usr/lib/libobjc.A.dylib", {
+    sel_registerName: { args: [FFIType.ptr], returns: FFIType.ptr },
+    objc_msgSend: { args: [FFIType.ptr, FFIType.ptr], returns: FFIType.ptr }
+  });
+
+  const utf8Sel = libobjc.symbols.sel_registerName(cstr("UTF8String")) as Pointer;
+
+  ffi = {
+    dlopen: (path, flags) => libdl.symbols.dlopen(path, flags) as Pointer,
+    dlsym: (handle, name) => libdl.symbols.dlsym(handle, name) as Pointer,
+    dlclose: (handle) => libdl.symbols.dlclose(handle) as number,
+    objc_msgSend: (obj, sel) => libobjc.symbols.objc_msgSend(obj, sel) as Pointer,
+    utf8Sel
+  };
+
+  return ffi;
+}
+
+/**
+ * Resolve extern NSString * constant values from a framework binary.
+ *
+ * Uses Bun's FFI to call dlopen/dlsym directly within the Bun process,
+ * avoiding the need to compile and execute a separate helper binary.
+ *
+ * @param frameworkBinaryPath - Path to the framework binary
+ *   (e.g., "/System/Library/Frameworks/Foundation.framework/Foundation")
+ * @param symbolNames - Array of extern symbol names to resolve
+ * @returns Map from symbol name to its string value
+ */
+export async function resolveStringConstants(
+  frameworkBinaryPath: string,
+  symbolNames: string[]
+): Promise<Map<string, string>> {
+  if (symbolNames.length === 0) {
+    return new Map();
+  }
+
+  const f = ensureFFI();
+
+  // Open the framework binary via dlopen (RTLD_LAZY = 1)
+  const handle = f.dlopen(cstr(frameworkBinaryPath), 1);
+  if (Number(handle) === 0) {
+    return new Map();
+  }
+
+  const result = new Map<string, string>();
+
+  try {
+    for (const symbolName of symbolNames) {
+      // dlsym returns the address of the global variable (NSString **)
+      const symAddr = f.dlsym(handle, cstr(symbolName));
+      if (Number(symAddr) === 0) continue;
+
+      // Dereference: read the NSString * pointer from the global variable
+      // read.ptr returns number; cast to Pointer for objc_msgSend
+      const nsStringPtr = read.ptr(symAddr, 0) as unknown as Pointer;
+      if (Number(nsStringPtr) === 0) continue;
+
+      // Call [nsString UTF8String] via objc_msgSend -> returns const char *
+      const utf8Ptr = f.objc_msgSend(nsStringPtr, f.utf8Sel);
+      if (Number(utf8Ptr) === 0) continue;
+
+      // Read the C string value
+      const value = new CString(utf8Ptr).toString();
+      result.set(symbolName, value);
+    }
+  } finally {
+    f.dlclose(handle);
+  }
+
+  return result;
+}
+
+/**
+ * Clean up resources. No-op in the FFI implementation since we don't
+ * compile a helper binary, but kept for API compatibility.
+ */
+export async function cleanupResolver(): Promise<void> {
+  // No temp files to clean up in the FFI implementation
+}

package/generator/struct-fields.ts

@@ -0,0 +1,46 @@
+/**
+ * Parses the KNOWN_STRUCT_FIELDS table from the objc-js native runtime.
+ * This table defines the field names that the bridge assigns to struct properties
+ * at the JS level. Structs not in this table get positional names (field0, field1, ...).
+ */
+
+import { join } from "path";
+
+/** Path to the objc-js struct-utils.h header containing KNOWN_STRUCT_FIELDS. */
+const STRUCT_UTILS_PATH = join(import.meta.dir, "..", "node_modules", "objc-js", "src", "native", "struct-utils.h");
+
+/**
+ * Parse the KNOWN_STRUCT_FIELDS C++ map from struct-utils.h.
+ * Returns a map of struct name → field names array.
+ *
+ * The C++ source looks like:
+ * ```cpp
+ * {"CGPoint", {"x", "y"}},
+ * {"NSRange", {"location", "length"}},
+ * ```
+ */
+export async function parseKnownStructFields(): Promise<Map<string, string[]>> {
+  const content = await Bun.file(STRUCT_UTILS_PATH).text();
+  const result = new Map<string, string[]>();
+
+  // Match each entry: {"StructName", {"field1", "field2", ...}},
+  const entryRe = /\{"(\w+)",\s*\{([^}]+)\}\}/g;
+  let match: RegExpExecArray | null;
+
+  while ((match = entryRe.exec(content)) !== null) {
+    const structName = match[1]!;
+    const fieldsStr = match[2]!;
+    // Extract individual field name strings
+    const fields: string[] = [];
+    const fieldRe = /"(\w+)"/g;
+    let fieldMatch: RegExpExecArray | null;
+    while ((fieldMatch = fieldRe.exec(fieldsStr)) !== null) {
+      fields.push(fieldMatch[1]!);
+    }
+    if (fields.length > 0) {
+      result.set(structName, fields);
+    }
+  }
+
+  return result;
+}

package/generator/templates/bind.ts

@@ -0,0 +1,100 @@
+/**
+ * Internal helper for binding ObjC class constants with `instanceof` support.
+ *
+ * Separated from helpers.ts to avoid circular imports — framework index files
+ * import this, and helpers.ts imports from Foundation's index.
+ *
+ * @internal
+ */
+
+import type { NobjcObject } from "objc-js";
+
+/**
+ * Cache of `isKindOfClass$` results: obj → (cls → result).
+ *
+ * After the first check for a given (obj, cls) pair crosses the JS↔ObjC
+ * boundary, subsequent checks on the same object return the cached result
+ * with zero native calls.  This matters for if/else chains that are hit
+ * repeatedly (e.g. in event handlers or render loops).
+ */
+const _kindCache = new WeakMap<object, Map<object, boolean>>();
+
+/**
+ * Cached `isKindOfClass:` check — the single path used by both
+ * `instanceof` (via `Symbol.hasInstance`) and the `isKindOfClass()` helper.
+ */
+function _isKindOfClass(obj: any, cls: any): boolean {
+  if (typeof obj !== "object" || obj === null) return false;
+  let m = _kindCache.get(obj);
+  if (m) {
+    const v = m.get(cls);
+    if (v !== undefined) return v;
+  }
+  try {
+    if (!m) {
+      m = new Map();
+      _kindCache.set(obj, m);
+    }
+    const r = obj.isKindOfClass$(cls);
+    m.set(cls, r);
+    return r;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Type guard that narrows an ObjC object to a specific class type using
+ * the Objective-C runtime's `-[NSObject isKindOfClass:]` check.
+ *
+ * Results are cached per (object, class) pair so repeated checks skip
+ * the native boundary crossing entirely.
+ *
+ * Returns `true` if `obj` is an instance of `cls` or any of its subclasses,
+ * and narrows the TypeScript type accordingly.
+ *
+ * @param obj  - The object to check
+ * @param cls  - The runtime class constant (e.g. `NSWindow`, `NSString`)
+ * @returns `true` if `obj` is a kind of `cls`
+ *
+ * @example
+ * ```ts
+ * import {
+ *   ASAuthorizationAppleIDCredential,
+ *   type _ASAuthorizationAppleIDCredential,
+ *   ASPasswordCredential,
+ *   type _ASPasswordCredential,
+ * } from "./AuthenticationServices";
+ * import { isKindOfClass } from "./helpers";
+ *
+ * const cred = authorization.credential();
+ *
+ * if (isKindOfClass<_ASAuthorizationAppleIDCredential>(cred, ASAuthorizationAppleIDCredential)) {
+ *   cred.user();   // narrowed to _ASAuthorizationAppleIDCredential
+ *   cred.email();
+ * } else if (isKindOfClass<_ASPasswordCredential>(cred, ASPasswordCredential)) {
+ *   cred.user();
+ *   cred.password();
+ * }
+ * ```
+ */
+export function isKindOfClass<T extends NobjcObject>(obj: NobjcObject, cls: any): obj is T {
+  return _isKindOfClass(obj, cls);
+}
+
+/**
+ * Load a class constant from a framework library and patch
+ * `Symbol.hasInstance` so that `obj instanceof ClassName` works at runtime
+ * by delegating to the ObjC runtime's `-[NSObject isKindOfClass:]`.
+ *
+ * Uses the same cached check as `isKindOfClass()`.
+ *
+ * @internal
+ */
+export function _bindClass<T>(lib: any, name: string): T {
+  const cls = lib[name];
+  Object.defineProperty(cls, Symbol.hasInstance, {
+    value: (obj: any) => _isKindOfClass(obj, cls)
+  });
+  return cls as unknown as T;
+}

package/generator/templates/helpers.ts

@@ -0,0 +1,70 @@
+import type { NobjcObject } from "objc-js";
+import {
+  NSArray,
+  NSDictionary,
+  NSString,
+  type _NSArray,
+  type _NSDictionary,
+  type _NSString
+} from "./Foundation/index.js";
+
+/**
+ * Create NSString from a JavaScript string
+ * @param str The string object
+ * @returns An NSString object
+ */
+export function NSStringFromString(str: string): _NSString {
+  const nsString = NSString.stringWithUTF8String$(str);
+  if (!nsString) {
+    throw new Error(`Failed to create NSString from string: ${str}`);
+  }
+  return nsString;
+}
+
+/**
+ * Combine NS_OPTIONS values using bitwise OR.
+ *
+ * Accepts any number of option flag values and returns their bitwise
+ * combination, preserving the NS_OPTIONS type for type safety.
+ *
+ * @example
+ * ```ts
+ * import { NSWindowStyleMask } from "./AppKit";
+ * import { options } from "./helpers";
+ *
+ * const mask = options(
+ *   NSWindowStyleMask.Titled,
+ *   NSWindowStyleMask.Closable,
+ *   NSWindowStyleMask.Resizable,
+ * );
+ * ```
+ */
+export function options<T extends number>(...values: T[]): T {
+  let result = 0;
+  for (const v of values) {
+    result |= v;
+  }
+  return result as T;
+}
+
+export function NSArrayFromObjects(objects: NobjcObject[]): _NSArray {
+  if (objects.length === 0) {
+    return NSArray.array();
+  }
+  let array = NSArray.arrayWithObject$(objects[0]!);
+  for (let i = 1; i < objects.length; i++) {
+    array = array.arrayByAddingObject$(objects[i]!);
+  }
+  return array;
+}
+
+export function NSDictionaryFromKeysAndValues(keys: NobjcObject[], values: NobjcObject[]): _NSDictionary {
+  if (keys.length !== values.length) {
+    throw new Error("Keys and values arrays must have the same length");
+  }
+  const keysArray = NSArrayFromObjects(keys);
+  const valuesArray = NSArrayFromObjects(values);
+  return NSDictionary.dictionaryWithObjects$forKeys$(valuesArray, keysArray);
+}
+
+export { isKindOfClass } from "./bind.js";

package/generator/templates/nsdata.ts

@@ -0,0 +1,97 @@
+import { NSData, type _NSData } from "./Foundation/index.js";
+import { NSStringFromString } from "./helpers.js";
+
+/**
+ * Create NSData from a JavaScript Buffer
+ * @param buffer The Buffer object
+ * @returns An NSData object
+ */
+export function NSDataFromBuffer(buffer: Buffer): _NSData {
+  return NSData.dataWithBytes$length$(buffer, buffer.length);
+}
+
+/**
+ * Convert NSData to a JavaScript Buffer using base64 encoding
+ * This is the most reliable method for data conversion.
+ * @param data The NSData object
+ * @returns A Buffer containing the data
+ */
+export function bufferFromNSData(data: _NSData): Buffer {
+  const nsData = data as unknown as typeof NSData.prototype;
+  const length = nsData.length();
+
+  if (length === 0) {
+    return Buffer.alloc(0);
+  }
+
+  // Use base64 encoding as a reliable bridge between NSData and JS Buffer
+  const base64String = nsData.base64EncodedStringWithOptions$(0);
+  const base64Str = base64String.UTF8String();
+  return Buffer.from(base64Str, "base64");
+}
+
+/**
+ * Convert NSData to a JavaScript Buffer using direct memory copy
+ * This method uses getBytes:length: for direct memory access.
+ * May be more efficient for large data, but requires proper buffer allocation.
+ * @param data The NSData object
+ * @returns A Buffer containing the data
+ */
+export function bufferFromNSDataDirect(data: _NSData): Buffer {
+  const nsData = data as unknown as typeof NSData.prototype;
+  const length = nsData.length();
+
+  if (length === 0) {
+    return Buffer.alloc(0);
+  }
+
+  // Allocate a buffer and copy bytes directly
+  const buffer = Buffer.alloc(length);
+  nsData.getBytes$length$(buffer, length);
+  return buffer;
+}
+
+/**
+ * Convert NSData to a JavaScript Uint8Array
+ * @param data The NSData object
+ * @returns A Uint8Array containing the data
+ */
+export function uint8ArrayFromNSData(data: _NSData): Uint8Array {
+  const buffer = bufferFromNSData(data);
+  return new Uint8Array(buffer);
+}
+
+/**
+ * Convert NSData to a base64 string
+ * @param data The NSData object
+ * @returns A base64-encoded string
+ */
+export function base64FromNSData(data: _NSData): string {
+  const nsString = data.base64EncodedStringWithOptions$(0);
+  return nsString.UTF8String();
+}
+
+/**
+ * Create NSData from a base64 string
+ * @param base64String The base64-encoded string
+ * @returns An NSData object
+ */
+export function NSDataFromBase64(base64String: string): _NSData {
+  const nsString = NSStringFromString(base64String);
+  const nsDataAlloc = NSData.alloc();
+  const nsData = nsDataAlloc.initWithBase64EncodedString$options$(nsString, 0);
+  if (!nsData) {
+    throw new Error(`Failed to create NSData from base64 string: ${base64String}`);
+  }
+  return nsData;
+}
+
+/**
+ * Get the length of NSData
+ * @param data The NSData object
+ * @returns The length in bytes
+ */
+export function NSDataLength(data: _NSData): number {
+  const nsData = data as unknown as typeof NSData.prototype;
+  return nsData.length();
+}