Deno

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

Classes

Deno.UnsafeCallback

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

Deno.UnsafeFnPointer

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

Deno.UnsafePointer

A collection of static functions for interacting with pointer objects.

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).

Functions

Deno.dlopen

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

Interfaces

Deno.DynamicLibrary

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

Deno.ForeignFunction

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

Deno.ForeignLibraryInterface

A foreign library interface descriptor.

Deno.ForeignStatic

No documentation available

Deno.NativeStructType

The native struct type for interfacing with foreign functions.

struct

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.

brand

Deno.UnsafeCallbackDefinition

Definition of a unsafe callback function.

Type Aliases

Deno.ConditionalAsync

No documentation available

Deno.FromForeignFunction

No documentation available

Deno.FromNativeParameterTypes

No documentation available

Deno.FromNativeResultType

Type conversion for foreign symbol return types.

Deno.FromNativeType

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

Deno.NativeBigIntType

All BigInt number types for interfacing with foreign functions.

Deno.NativeBooleanType

The native boolean type for interfacing to foreign functions.

Deno.NativeBufferType

The native buffer type for interfacing to foreign functions.

Deno.NativeFunctionType

The native function type for interfacing with foreign functions.

Deno.NativeI16Enum

No documentation available

Deno.NativeI32Enum

No documentation available

Deno.NativeI8Enum

No documentation available

Deno.NativeNumberType

All plain number types for interfacing with foreign functions.

Deno.NativePointerType

The native pointer type for interfacing to foreign functions.

Deno.NativeResultType

No documentation available

Deno.NativeType

All supported types for interfacing with foreign functions.

Deno.NativeTypedFunction

No documentation available

Deno.NativeTypedPointer

No documentation available

Deno.NativeU16Enum

No documentation available

Deno.NativeU32Enum

No documentation available

Deno.NativeU8Enum

No documentation available

Deno.NativeVoidType

The native void type for interfacing with foreign functions.

Deno.PointerValue

Pointers are represented either with a PointerObject object or a null if the pointer is null.

Deno.StaticForeignLibraryInterface

A utility type that infers a foreign library interface.

Deno.StaticForeignSymbol

A utility type that infers a foreign symbol.

Deno.StaticForeignSymbolReturnType

No documentation available

Deno.ToNativeParameterTypes

A utility type for conversion of parameter types of foreign functions.

Deno.ToNativeResultType

Type conversion for unsafe callback return types.

Deno.ToNativeType

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

Deno.UnsafeCallbackFunction

An unsafe callback function.

Variables

Deno.brand

No documentation available

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 | BufferSource): 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

Constructors #

#UnsafePointerView(pointer: PointerObject)

new

Properties #

#pointer: PointerObject

Methods #

#copyInto(destination: BufferSource,
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: BufferSource,
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