bun-ffi-interop-pattern

What problem does it solve?

Bun FFI users often hit crashes or subtle memory bugs when loading native libraries, passing pointers/structs, and reading native memory without correct layout or cleanup.

Core Features & Use Cases

• Crash-safe library loading: Uses lazy loading instead of calling dlopen at module top-level to avoid startup failures.
• Struct interop guardrails: Prevents incorrect pass-by-value struct usage by recommending pointer passing or ABI-based argument splitting.
• Correct native memory handling: Enforces explicit buffer sizes, explicit endianness when reading, safe CString handling, and mandatory frees in finally blocks.
• Reliable layout guidance: Refuses to guess struct offsets and instructs generating offsets via a small C program using sizeof/offsetof.
• Type-safe parsing wrapper pattern: Encourages building typed read functions with verified offsets and structure sizes.

Quick Start

Use bun:ffi to lazily dlopen your shared library, read returned pointers with correct byte lengths and endianness, and free any native allocations in a finally block.