Symbol

dlopen

function dlopen<Fns extends Record<string, FFIFunction>>(name: string | URL | BunFile, symbols: Fns): Library<Fns>

Open a library using "bun:ffi"

@param name

The name of the library or file path. This will be passed to dlopen()

@param symbols

Map of symbols to load where the key is the symbol name and the value is the FFIFunction

import {dlopen} from 'bun:ffi';

const lib = dlopen("duckdb.dylib", {
  get_version: {
    returns: "cstring",
    args: [],
  },
});
lib.symbols.get_version();
// "1.0.0"

This is powered by just-in-time compiling C wrappers that convert JavaScript types to C types and back. Internally, bun uses tinycc, so a big thanks goes to Fabrice Bellard and TinyCC maintainers for making this possible.

Referenced types

class URL

The URL interface represents an object providing static methods used for creating object URLs.

MDN Reference

hash: string
MDN Reference
host: string
MDN Reference
hostname: string
MDN Reference
href: string
MDN Reference
readonly origin: string
MDN Reference
password: string
MDN Reference
pathname: string
MDN Reference
port: string
MDN Reference
protocol: string
MDN Reference
search: string
MDN Reference
readonly searchParams: URLSearchParams
MDN Reference
username: string
MDN Reference
toJSON(): string
MDN Reference
toString(): string
static canParse(url: string | URL, base?: string | URL): boolean
MDN Reference
static createObjectURL(obj: Blob | MediaSource): string
MDN Reference
static parse(url: string | URL, base?: string | URL): null | URL
MDN Reference
static revokeObjectURL(url: string): void
MDN Reference

interface BunFile

Blob powered by the fastest system calls available for operating on files.

This Blob is lazy. That means it won't do any work until you read from it.

size will not be valid until the contents of the file are read at least once.
type is auto-set based on the file extension when possible

const file = Bun.file("./hello.json");
console.log(file.type); // "application/json"
console.log(await file.text()); // '{"hello":"world"}'

lastModified: number
A UNIX timestamp indicating when the file was last modified.
readonly name?: string
The name or path of the file, as specified in the constructor.
readonly readable: ReadableStream
readonly size: number
MDN Reference
readonly type: string
MDN Reference
arrayBuffer(): Promise<ArrayBuffer>
Returns a promise that resolves to the contents of the blob as an ArrayBuffer
bytes(): Promise<Uint8Array<ArrayBufferLike>>
Returns a promise that resolves to the contents of the blob as a Uint8Array (array of bytes) its the same as new Uint8Array(await blob.arrayBuffer())
delete(): Promise<void>
Deletes the file (same as unlink)
exists(): Promise<boolean>
Does the file exist?
This returns true for regular files and FIFOs. It returns false for directories. Note that a race condition can occur where the file is deleted or renamed after this is called but before you open it.
This does a system call to check if the file exists, which can be slow.
If using this in an HTTP server, it's faster to instead use return new Response(Bun.file(path)) and then an error handler to handle exceptions.
Instead of checking for a file's existence and then performing the operation, it is faster to just perform the operation and handle the error.
For empty Blob, this always returns true.
formData(): Promise<FormData>
Read the data from the blob as a FormData object.
This first decodes the data from UTF-8, then parses it as a multipart/form-data body or a application/x-www-form-urlencoded body.
The type property of the blob is used to determine the format of the body.
This is a non-standard addition to the Blob API, to make it conform more closely to the BodyMixin API.
json(): Promise<any>
Read the data from the blob as a JSON object.
This first decodes the data from UTF-8, then parses it as JSON.
slice(begin?: number, end?: number, contentType?: string): BunFile
Offset any operation on the file starting at begin and ending at end. end is relative to 0
Similar to TypedArray.subarray. Does not copy the file, open the file, or modify the file.
If begin > 0, () will be slower on macOS
@param begin
start offset in bytes
@param end
absolute offset in bytes (relative to 0)
@param contentType
MIME type for the new BunFile
slice(begin?: number, contentType?: string): BunFile
Offset any operation on the file starting at begin
Similar to TypedArray.subarray. Does not copy the file, open the file, or modify the file.
If begin > 0, Bun.write() will be slower on macOS
@param begin
start offset in bytes
@param contentType
MIME type for the new BunFile
slice(contentType?: string): BunFile
Slice the file from the beginning to the end, optionally with a new MIME type.
@param contentType
MIME type for the new BunFile
stat(): Promise<Stats>
Provides useful information about the file.
stream(): ReadableStream<Uint8Array<ArrayBufferLike>>
Returns a readable stream of the blob's contents
text(): Promise<string>
Returns a promise that resolves to the contents of the blob as a string
unlink(): Promise<void>
Deletes the file.
write(data: string | ArrayBuffer | SharedArrayBuffer | Request | Response | BunFile | ArrayBufferView<ArrayBufferLike>, options?: { highWaterMark: number }): Promise<number>
Write data to the file. This is equivalent to using Bun.write with a BunFile.
@param data
The data to write.
@param options
The options to use for the write.
writer(options?: { highWaterMark: number }): FileSink
Incremental writer for files and pipes.

interface Library<Fns extends Symbols>

symbols: ConvertFns<Fns>
close(): void
dlclose the library, unloading the symbols and freeing allocated memory.
Once called, the library is no longer usable.
Calling a function from a library that has been closed is undefined behavior.