FFI

import {dlopen, FFIType, suffix} from 'bun:ffi';

// `suffix` is either "dylib", "so", or "dll" depending on the platform
// you don't have to use "suffix", it's just there for convenience
const path = `libsqlite3.${suffix}`;

const {
	symbols: {
		sqlite3_libversion, // the function to call
	},
} = dlopen(
	path, // a library name or file path
	{
		sqlite3_libversion: {
			// no arguments, returns a string
			args: [],
			returns: FFIType.cstring,
		},
	},
);

console.log(`SQLite 3 version: ${sqlite3_libversion()}`);

import {dlopen, FFIType, suffix} from 'bun:ffi';
const {i32} = FFIType;

const path = `libadd.${suffix}`;

const lib = dlopen(path, {
	add: {
		args: [i32, i32],
		returns: i32,
	},
});

console.log(lib.symbols.add(1, 2));

// add.rs
#[no_mangle]
pub extern "C" fn add(a: i32, b: i32) -> i32 {
    a + b
}

rustc --crate-type cdylib add.rs

#include <cstdint>

extern "C" int32_t add(int32_t a, int32_t b) {
    return a + b;
}

zig build-lib add.cpp -dynamic -lc -lc++

class CString extends String {
	/**
	 * Given a `ptr`, this will automatically search for the closing `\0` character and transcode from UTF-8 to UTF-16 if necessary.
	 */
	constructor(ptr: number, byteOffset?: number, byteLength?: number): string;

	/**
	 * The ptr to the C string
	 *
	 * This `CString` instance is a clone of the string, so it
	 * is safe to continue using this instance after the `ptr` has been
	 * freed.
	 */
	ptr: number;
	byteOffset?: number;
	byteLength?: number;
}

const myString = new CString(ptr);

const myString = new CString(ptr, 0, byteLength);

my_library_free(myString.ptr);

// this is safe because myString is a clone
console.log(myString);

import { CFunction } from "bun:ffi";

let myNativeLibraryGetVersion = /* somehow, you got this pointer */

const getVersion = new CFunction({
  returns: "cstring",
  args: [],
  ptr: myNativeLibraryGetVersion,
});
getVersion();

import {linkSymbols} from 'bun:ffi';

// getVersionPtrs defined elsewhere
const [majorPtr, minorPtr, patchPtr] = getVersionPtrs();

const lib = linkSymbols({
	// Unlike with dlopen(), the names here can be whatever you want
	getMajor: {
		returns: 'cstring',
		args: [],

		// Since this doesn't use dlsym(), you have to provide a valid ptr
		// That ptr could be a number or a bigint
		// An invalid pointer will crash your program.
		ptr: majorPtr,
	},
	getMinor: {
		returns: 'cstring',
		args: [],
		ptr: minorPtr,
	},
	getPatch: {
		returns: 'cstring',
		args: [],
		ptr: patchPtr,
	},
});

const [major, minor, patch] = [
	lib.symbols.getMajor(),
	lib.symbols.getMinor(),
	lib.symbols.getPatch(),
];

import {dlopen, JSCallback, ptr, CString} from 'bun:ffi';

const {
	symbols: {search},
	close,
} = dlopen('libmylib', {
	search: {
		returns: 'usize',
		args: ['cstring', 'callback'],
	},
});

const searchIterator = new JSCallback((ptr, length) => /hello/.test(new CString(ptr, length)), {
	returns: 'bool',
	args: ['ptr', 'usize'],
});

const str = Buffer.from('wwutwutwutwutwutwutwutwutwutwutut\0', 'utf8');
if (search(ptr(str), searchIterator)) {
	// found a match!
}

// Sometime later:
setTimeout(() => {
	searchIterator.close();
	close();
}, 5000);

const searchIterator = new JSCallback((ptr, length) => /hello/.test(new CString(ptr, length)), {
	returns: 'bool',
	args: ['ptr', 'usize'],
	threadsafe: true, // Optional. Defaults to `false`
});

import {ptr} from 'bun:ffi';
let myTypedArray = new Uint8Array(32);
const myPtr = ptr(myTypedArray);

import {ptr, toArrayBuffer} from 'bun:ffi';
let myTypedArray = new Uint8Array(32);
const myPtr = ptr(myTypedArray);

// toArrayBuffer accepts a `byteOffset` and `byteLength`
// if `byteLength` is not provided, it is assumed to be a null-terminated pointer
myTypedArray = new Uint8Array(toArrayBuffer(myPtr, 0, 32), 0, 32);

import {toArrayBuffer} from 'bun:ffi';
let myDataView = new DataView(toArrayBuffer(myPtr, 0, 32));

console.log(
	myDataView.getUint8(0, true),
	myDataView.getUint8(1, true),
	myDataView.getUint8(2, true),
	myDataView.getUint8(3, true),
);

import {read} from 'bun:ffi';

console.log(
	// ptr, byteOffset
	read.u8(myPtr, 0),
	read.u8(myPtr, 1),
	read.u8(myPtr, 2),
	read.u8(myPtr, 3),
);

typedef void (*JSTypedArrayBytesDeallocator)(void *bytes, void *deallocatorContext);

import {toArrayBuffer} from 'bun:ffi';

// with a deallocatorContext:
toArrayBuffer(
	bytes,
	byteOffset,

	byteLength,

	// this is an optional pointer to a callback
	deallocatorContext,

	// this is a pointer to a function
	jsTypedArrayBytesDeallocator,
);

// without a deallocatorContext:
toArrayBuffer(
	bytes,
	byteOffset,

	byteLength,

	// this is a pointer to a function
	jsTypedArrayBytesDeallocator,
);

import {dlopen, FFIType} from 'bun:ffi';

const {
	symbols: {encode_png},
} = dlopen(myLibraryPath, {
	encode_png: {
		// FFIType's can be specified as strings too
		args: ['ptr', 'u32', 'u32'],
		returns: FFIType.ptr,
	},
});

const pixels = new Uint8ClampedArray(128 * 128 * 4);
pixels.fill(254);
pixels.subarray(0, 32 * 32 * 2).fill(0);

const out = encode_png(
	// pixels will be passed as a pointer
	pixels,

	128,
	128,
);

const out = encode_png(
	// pixels will be passed as a pointer
	pixels,

	// dimensions:
	128,
	128,
);

// assuming it is 0-terminated, it can be read like this:
let png = new Uint8Array(toArrayBuffer(out));

// save it to disk:
await Bun.write('out.png', png);