FFI

Foreign Function Interface. Call functions from shared libraries (e.g., C/C++) directly from Deno.

Useful for integrating with existing native code or accessing low-level system functionality.

Eg Deno.dlopen

class Deno.UnsafeCallback

An unsafe function pointer for passing JavaScript functions as C function pointers to foreign function calls.

The function pointer remains valid until the close() method is called.

All UnsafeCallback are always thread safe in that they can be called from foreign threads without crashing. However, they do not wake up the Deno event loop by default.

If a callback is to be called from foreign threads, use the threadSafe() static constructor or explicitly call ref() to have the callback wake up the Deno event loop when called from foreign threads. This also stops Deno's process from exiting while the callback still exists and is not unref'ed.

Use deref() to then allow Deno's process to exit. Calling deref() on a ref'ed callback does not stop it from waking up the Deno event loop when called from foreign threads.

Constructors

UnsafeCallback(

definition: Definition,

callback: UnsafeCallbackFunction<Definition["parameters"], Definition["result"]>,
)

new

Type Parameters

Definition extends UnsafeCallbackDefinition = UnsafeCallbackDefinition

Properties

callback: UnsafeCallbackFunction<Definition["parameters"], Definition["result"]>

readonly

The callback function.

definition: Definition

readonly

The definition of the unsafe callback.

pointer: PointerObject<Definition>

readonly

The pointer to the unsafe callback.

Methods

close(): void

Removes the C function pointer associated with this instance.

Continuing to use the instance or the C function pointer after closing the UnsafeCallback will lead to errors and crashes.

Calling this method sets the callback's reference counting to zero, stops the callback from waking up the Deno event loop when called from foreign threads and no longer keeps Deno's process from exiting.

ref(): number

Increments the callback's reference counting and returns the new reference count.

After ref() has been called, the callback always wakes up the Deno event loop when called from foreign threads.

If the callback's reference count is non-zero, it keeps Deno's process from exiting.

unref(): number

Decrements the callback's reference counting and returns the new reference count.

Calling unref() does not stop a callback from waking up the Deno event loop when called from foreign threads.

If the callback's reference counter is zero, it no longer keeps Deno's process from exiting.

Static Methods

threadSafe<Definition extends UnsafeCallbackDefinition = UnsafeCallbackDefinition>(

definition: Definition,

callback: UnsafeCallbackFunction<Definition["parameters"], Definition["result"]>,
): UnsafeCallback<Definition>

Creates an UnsafeCallback and calls ref() once to allow it to wake up the Deno event loop when called from foreign threads.

This also stops Deno's process from exiting while the callback still exists and is not unref'ed.

class Deno.UnsafeFnPointer

An unsafe pointer to a function, for calling functions that are not present as symbols.

Constructors

UnsafeFnPointer(

pointer: PointerObject<NoInfer<Omit<Fn, "nonblocking">>>,

definition: Fn,
)

new

Type Parameters

Fn extends ForeignFunction

Properties

call: FromForeignFunction<Fn>

Call the foreign function.

definition: Fn

The definition of the function.

pointer: PointerObject<Fn>

The pointer to the function.

class Deno.UnsafePointer

A collection of static functions for interacting with pointer objects.

Static Methods

create<T = unknown>(value: bigint): PointerValue<T>

Create a pointer from a numeric value. This one is really dangerous!

equals<T = unknown>(

a: PointerValue<T>,

b: PointerValue<T>,
): boolean

Returns true if the two pointers point to the same address.

of<T = unknown>(value: Deno.UnsafeCallback | AllowSharedBufferSource): PointerValue<T>

Return the direct memory pointer to the typed array in memory.

offset<T = unknown>(

value: PointerObject,

offset: number,
): PointerValue<T>

Return a new pointer offset from the original by offset bytes.

value(value: PointerValue): bigint

Get the numeric value of a pointer

class Deno.UnsafePointerView

An unsafe pointer view to a memory location as specified by the pointer value. The UnsafePointerView API follows the standard built in interface DataView for accessing the underlying types at an memory location (numbers, strings and raw bytes).

Constructors

UnsafePointerView(pointer: PointerObject)

new

Properties

pointer: PointerObject

Methods

copyInto(

destination: AllowSharedBufferSource,

offset?: number,
): void

Copies the memory of the pointer into a typed array.

Length is determined from the typed array's byteLength.

Also takes optional byte offset from the pointer.

getArrayBuffer(

byteLength: number,

offset?: number,
): ArrayBuffer

Gets an ArrayBuffer of length byteLength at the specified byte offset from the pointer.

getBigInt64(offset?: number): bigint

Gets a signed 64-bit integer at the specified byte offset from the pointer.

getBigUint64(offset?: number): bigint

Gets an unsigned 64-bit integer at the specified byte offset from the pointer.

getBool(offset?: number): boolean

Gets a boolean at the specified byte offset from the pointer.

getCString(offset?: number): string

Gets a UTF-8 encoded string at the specified byte offset until 0 byte.

Returned string doesn't include U+0000 character.

Invalid UTF-8 characters are replaced with U+FFFD character in the returned string.

getFloat32(offset?: number): number

Gets a signed 32-bit float at the specified byte offset from the pointer.

getFloat64(offset?: number): number

Gets a signed 64-bit float at the specified byte offset from the pointer.

getInt16(offset?: number): number

Gets a signed 16-bit integer at the specified byte offset from the pointer.

getInt32(offset?: number): number

Gets a signed 32-bit integer at the specified byte offset from the pointer.

getInt8(offset?: number): number

Gets a signed 8-bit integer at the specified byte offset from the pointer.

getPointer<T = unknown>(offset?: number): PointerValue<T>

Gets a pointer at the specified byte offset from the pointer

getUint16(offset?: number): number

Gets an unsigned 16-bit integer at the specified byte offset from the pointer.

getUint32(offset?: number): number

Gets an unsigned 32-bit integer at the specified byte offset from the pointer.

getUint8(offset?: number): number

Gets an unsigned 8-bit integer at the specified byte offset from the pointer.

Static Methods

copyInto(

pointer: PointerObject,

destination: AllowSharedBufferSource,

offset?: number,
): void

Copies the memory of the specified pointer into a typed array.

Length is determined from the typed array's byteLength.

Also takes optional byte offset from the pointer.

getArrayBuffer(

pointer: PointerObject,

byteLength: number,

offset?: number,
): ArrayBuffer

Gets an ArrayBuffer of length byteLength at the specified byte offset from the specified pointer.

getCString(

pointer: PointerObject,

offset?: number,
): string

Gets a UTF-8 encoded string at the specified byte offset from the specified pointer until 0 byte.

Returned string doesn't include U+0000 character.

Invalid UTF-8 characters are replaced with U+FFFD character in the returned string.

function Deno.dlopen

allow-ffi

dlopen<S extends ForeignLibraryInterface>(

filename: string | URL,

symbols: S,
): DynamicLibrary<S>

Opens an external dynamic library and registers symbols, making foreign functions available to be called.

Requires allow-ffi permission. Loading foreign dynamic libraries can in theory bypass all of the sandbox permissions. While it is a separate permission users should acknowledge in practice that is effectively the same as running with the allow-all permission.

Examples

// Determine library extension based on
// your OS.
let libSuffix = "";
switch (Deno.build.os) {
  case "windows":
    libSuffix = "dll";
    break;
  case "darwin":
    libSuffix = "dylib";
    break;
  default:
    libSuffix = "so";
    break;
}

const libName = `./libadd.${libSuffix}`;
// Open library and define exported symbols
const dylib = Deno.dlopen(
  libName,
  {
    "add": { parameters: ["isize", "isize"], result: "isize" },
  } as const,
);

// Call the symbol `add`
const result = dylib.symbols.add(35n, 34n); // 69n

console.log(`Result from external addition of 35 and 34: ${result}`);

Type Parameters

S extends ForeignLibraryInterface

Parameters

filename: string | URL

symbols: S

Return Type

DynamicLibrary<S>

interface Deno.DynamicLibrary

A dynamic library resource. Use Deno.dlopen to load a dynamic library and return this interface.

Type Parameters

S extends ForeignLibraryInterface

Properties

symbols: StaticForeignLibraryInterface<S>

All of the registered library along with functions for calling them.

Methods

close(): void

Removes the pointers associated with the library symbols.

Continuing to use symbols that are part of the library will lead to errors and crashes.

Calling this method will also immediately set any references to zero and will no longer keep Deno's process from exiting.

interface Deno.ForeignFunction

The interface for a foreign function as defined by its parameter and result types.

Type Parameters

Parameters extends readonly NativeType[] = readonly NativeType[]

Result extends NativeResultType = NativeResultType

NonBlocking extends boolean = boolean

Properties

name: string

optional

Name of the symbol.

Defaults to the key name in symbols object.

parameters: Parameters

The parameters of the foreign function.

result: Result

The result (return value) of the foreign function.

nonblocking: NonBlocking

optional

When true, function calls will run on a dedicated blocking thread and will return a Promise resolving to the result.

optional: boolean = false

optional

When true, dlopen will not fail if the symbol is not found. Instead, the symbol will be set to null.

interface Deno.ForeignLibraryInterface

A foreign library interface descriptor.

Index Signatures

[name: string]: ForeignFunction | ForeignStatic

interface Deno.ForeignStatic

Type Parameters

Type extends NativeType = NativeType

Properties

name: string

optional

Name of the symbol, defaults to the key name in symbols object.

type: Type

The type of the foreign static value.

optional: boolean = false

optional

When true, dlopen will not fail if the symbol is not found. Instead, the symbol will be set to null.

interface Deno.NativeStructType

The native struct type for interfacing with foreign functions.

Properties

struct: readonly NativeType[]

readonly

interface Deno.PointerObject

A non-null pointer, represented as an object at runtime. The object's prototype is null and cannot be changed. The object cannot be assigned to either and is thus entirely read-only.

To interact with memory through a pointer use the UnsafePointerView class. To create a pointer from an address or the get the address of a pointer use the static methods of the UnsafePointer class.

Type Parameters

T = unknown

Properties

[brand]: T

interface Deno.UnsafeCallbackDefinition

Definition of a unsafe callback function.

Type Parameters

Parameters extends readonly NativeType[] = readonly NativeType[]

Result extends NativeResultType = NativeResultType

Properties

parameters: Parameters

The parameters of the callbacks.

result: Result

The current result of the callback.

type alias Deno.ConditionalAsync

Type Parameters

IsAsync extends boolean | undefined

T

Definition

IsAsync extends true ? Promise<T> : T

type alias Deno.FromForeignFunction

Type Parameters

T extends ForeignFunction

Definition

T["parameters"] extends readonly [] ? () => StaticForeignSymbolReturnType<T> : (...args: ToNativeParameterTypes<T["parameters"]>) => StaticForeignSymbolReturnType<T>

type alias Deno.FromNativeParameterTypes

Type Parameters

T extends readonly NativeType[]

Definition

[T[number][]] extends [T] ? FromNativeType<T[number]>[] : [readonly T[number][]] extends [T] ? readonly FromNativeType<T[number]>[] : T extends readonly [...NativeType[]] ? [K in keyof T]: FromNativeType<T[K]> : never

type alias Deno.FromNativeResultType

Type conversion for foreign symbol return types.

Type Parameters

T extends NativeResultType = NativeResultType

Definition

T extends NativeStructType ? Uint8Array<ArrayBuffer> : T extends NativeNumberType ? T extends NativeU8Enum<infer U> ? U : T extends NativeI8Enum<infer U> ? U : T extends NativeU16Enum<infer U> ? U : T extends NativeI16Enum<infer U> ? U : T extends NativeU32Enum<infer U> ? U : T extends NativeI32Enum<infer U> ? U : number : T extends NativeBigIntType ? bigint : T extends NativeBooleanType ? boolean : T extends NativePointerType ? T extends NativeTypedPointer<infer U> ? U | null : PointerValue : T extends NativeBufferType ? PointerValue : T extends NativeFunctionType ? T extends NativeTypedFunction<infer U> ? PointerObject<U> | null : PointerValue : T extends NativeVoidType ? void : never

type alias Deno.FromNativeType

Type conversion for foreign symbol return types and unsafe callback parameters.

Type Parameters

T extends NativeType = NativeType

Definition

T extends NativeStructType ? Uint8Array<ArrayBuffer> : T extends NativeNumberType ? T extends NativeU8Enum<infer U> ? U : T extends NativeI8Enum<infer U> ? U : T extends NativeU16Enum<infer U> ? U : T extends NativeI16Enum<infer U> ? U : T extends NativeU32Enum<infer U> ? U : T extends NativeI32Enum<infer U> ? U : number : T extends NativeBigIntType ? bigint : T extends NativeBooleanType ? boolean : T extends NativePointerType ? T extends NativeTypedPointer<infer U> ? U | null : PointerValue : T extends NativeBufferType ? PointerValue : T extends NativeFunctionType ? T extends NativeTypedFunction<infer U> ? PointerObject<U> | null : PointerValue : never

type alias Deno.NativeBigIntType

All BigInt number types for interfacing with foreign functions.

Definition


"u64"
 | "i64"
 | "usize"
 | "isize"

type alias Deno.NativeBooleanType

The native boolean type for interfacing to foreign functions.

Definition

"bool"

type alias Deno.NativeBufferType

The native buffer type for interfacing to foreign functions.

Definition

type alias Deno.NativeResultType

Definition

NativeType | NativeVoidType

type alias Deno.NativeType

All supported types for interfacing with foreign functions.

Definition


NativeNumberType
 | NativeBigIntType
 | NativeBooleanType
 | NativePointerType
 | NativeBufferType
 | NativeFunctionType
 | NativeStructType

Parameters extends readonly NativeType[] = readonly NativeType[]

Result extends NativeResultType = NativeResultType

Definition

Parameters extends readonly [] ? () => ToNativeResultType<Result> : (...args: FromNativeParameterTypes<Parameters>) => ToNativeResultType<Result>

variable Deno.brand

Type

unique symbol