FFI

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

// `suffix` 根據平臺可能是 "dylib"、"so" 或 "dll"
// 你不必一定要使用 "suffix"，它只是為方便準備的
const path = `libsqlite3.${suffix}`;

const {
  symbols: {
    sqlite3_libversion, // 要呼叫的函式
  },
} = dlopen(
  path, // 庫名或檔案路徑
  {
    sqlite3_libversion: {
      // 無引數，傳回字串
      args: [],
      returns: FFIType.cstring,
    },
  },
);

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

pub export fn add(a: i32, b: i32) i32 {
  return a + b;
}

zig build-lib add.zig -dynamic -OReleaseFast

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

# Linux
clang++ -shared -fPIC add.cpp -o libadd.so

# macOS
clang++ -dynamiclib add.cpp -o libadd.dylib

const {
  symbols: { write_all },
} = dlopen(path, {
  // C：size_t write_all(int fd, const void *buf, size_t len)
  write_all: { args: ["i32", "buffer", "buffer_length"], returns: "u64" },
});
const chunk = new TextEncoder().encode("hello");
write_all(1, chunk, chunk); // buf 和 len 都來自 `chunk`

CString(ptr: number, byteOffset?: number, byteLength?: number): string;

const myString = new CString(ptr);

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

const myString = new CString(ptr);
my_library_free(ptr);

// 這很安全，因為 myString 是克隆的
console.log(myString);

symbols.puts("Hello, world!"); // args: ["cstring"] — 直接傳入字串

import { CFunction } from "bun:ffi";

let myNativeLibraryGetVersion = /* 你以某種方式獲得的指標 */

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

import { linkSymbols } from "bun:ffi";

// getVersionPtrs 在其他地方定義
const [majorPtr, minorPtr, patchPtr] = getVersionPtrs();

const lib = linkSymbols({
  // 和 dlopen() 不同，這裡的名稱可以隨意
  getMajor: {
    returns: "cstring",
    args: [],

    // 由於不用 dlsym()，必須提供一個有效的指標
    // 該指標可以是 number 或 bigint
    // 無效指標會導致程式崩潰。
    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, 0, Number(length))), {
  returns: "bool",
  args: ["ptr", "usize"],
});

const str = Buffer.from("wwutwutwutwutwutwutwutwutwutwutut\0", "utf8");
if (search(ptr(str), searchIterator)) {
  // 找到匹配！
}

// 過一會兒：
setTimeout(() => {
  searchIterator.close();
  close();
}, 5000);

const searchIterator = new JSCallback((ptr, length) => /hello/.test(new CString(ptr, 0, Number(length))), {
  returns: "bool",
  args: ["ptr", "usize"],
  threadsafe: true, // 可選，預設為 `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 接受 `byteOffset` 和 `byteLength`
// 如果不傳 `byteLength`，預設為 null 結尾指標
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";

// 傳遞 deallocatorContext:
toArrayBuffer(
  bytes,
  byteOffset,

  byteLength,

  // 這是一個指向上下文的可選指標
  deallocatorContext,

  // 這是一個指向函式的指標
  jsTypedArrayBytesDeallocator,
);

// 不傳 deallocatorContext:
toArrayBuffer(
  bytes,
  byteOffset,

  byteLength,

  // 這是一個指向函式的指標
  jsTypedArrayBytesDeallocator,
);

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

const {
  symbols: { encode_png },
} = dlopen(myLibraryPath, {
  encode_png: {
    // FFIType 也可以用字串形式指定
    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 會作為指標傳入
  pixels,

  128,
  128,
);

const out = encode_png(
  // pixels 會作為指標傳入
  pixels,

  // 尺寸：
  128,
  128,
);

// 假設這是以 0 結尾，可以這樣讀取：
let png = new Uint8Array(toArrayBuffer(out));

// 寫入磁碟：
await Bun.write("out.png", png);