BuildDocsReferenceGuidesBlog
Discord logo
Discord
GitHub logo
Bun

class

ffi.DynamicLibrary

  • readonly path: string

    The path used to load the library.

  • readonly symbols: {
    __index[
    symbol: string
    ]: bigint;
     }

    An object containing previously resolved symbol addresses as bigint values.

  • Calls library.close(). This allows DynamicLibrary instances to be used with the using declaration for automatic cleanup when the enclosing scope exits. It is a no-op on a library that has already been closed.

  • close(): void;

    Closes the library handle.

    DynamicLibrary implements the explicit resource management protocol, so a library instance can be managed with the using declaration. Leaving the enclosing scope invokes library.close() automatically.

    import { DynamicLibrary } from 'node:ffi';

{
  using lib = new DynamicLibrary('./mylib.so');
  // Use `lib` here; `lib.close()` is called when the block exits.
}

    Calling library.close() (or disposing the library) more than once is a no-op.

    After a library has been closed:

    • Resolved function wrappers become invalid.
    • Further symbol and function resolution throws.
    • Registered callbacks are invalidated.

    Closing a library does not make previously exported callback pointers safe to reuse. Node.js does not track or revoke callback pointers that have already been handed to native code.

    If native code still holds a callback pointer after library.close() or after library.unregisterCallback(pointer), invoking that pointer has undefined behavior, is not allowed, and is dangerous: it can crash the process, produce incorrect output, or corrupt memory. Native code must stop using callback addresses before the library is closed or before the callback is unregistered.

    Calling library.close() from one of the library's active callbacks is unsupported and dangerous. The callback must return before the library is closed.

  • name: string,
    signature: T

    Resolves a symbol and returns a callable JavaScript wrapper.

    The returned function has a .pointer property containing the native function address as a bigint.

    If the same symbol has already been resolved, requesting it again with a different signature throws.

    const { DynamicLibrary } = require('node:ffi');

const lib = new DynamicLibrary('./mylib.so');
const add = lib.getFunction('add_i32', {
  arguments: ['i32', 'i32'],
  return: 'i32',
});

console.log(add(20, 22));
console.log(add.pointer);
  • getFunctions(): {
    __index[
    symbol: string
    ]: WrappedFunction<any, any[]>;
     }    ;

    When definitions is provided, resolves each named symbol and returns an object containing callable wrappers.

    When definitions is omitted, returns wrappers for all functions that have already been resolved on the library.

    definitions: T

    When definitions is provided, resolves each named symbol and returns an object containing callable wrappers.

    When definitions is omitted, returns wrappers for all functions that have already been resolved on the library.

  • name: string
    ): bigint;

    Resolves a symbol and returns its native address as a bigint.

  • getSymbols(): Record<string, bigint>;

    Returns an object containing all previously resolved symbol addresses.

  • pointer: bigint
    ): void;

    Keeps the callback strongly referenced by JavaScript.

  • callback: () => void
    ): bigint;

    Creates a native callback pointer backed by a JavaScript function.

    When signature is omitted, the callback uses a default void () signature.

    The return value is the callback pointer address as a bigint. It can be passed to native functions expecting a callback pointer.

    const { DynamicLibrary } = require('node:ffi');

const lib = new DynamicLibrary('./mylib.so');

const callback = lib.registerCallback(
  { arguments: ['i32'], return: 'i32' },
  (value) => value * 2,
);

    Callbacks are subject to the following restrictions:

    • They must be invoked on the same system thread where they were created.
    • They must not throw exceptions.
    • They must not return promises.
    • They must return a value compatible with the declared return type.
    • They must not call library.close() on their owning library while running.
    • They must not unregister themselves while running.

    Closing the owning library or unregistering the currently executing callback from inside the callback is unsupported and dangerous. Doing so may crash the process, produce incorrect output, or corrupt memory.

    signature: T,
    callback: CallbackFunctionFromSignature<T>
    ): bigint;

    Creates a native callback pointer backed by a JavaScript function.

    When signature is omitted, the callback uses a default void () signature.

    The return value is the callback pointer address as a bigint. It can be passed to native functions expecting a callback pointer.

    const { DynamicLibrary } = require('node:ffi');

const lib = new DynamicLibrary('./mylib.so');

const callback = lib.registerCallback(
  { arguments: ['i32'], return: 'i32' },
  (value) => value * 2,
);

    Callbacks are subject to the following restrictions:

    • They must be invoked on the same system thread where they were created.
    • They must not throw exceptions.
    • They must not return promises.
    • They must return a value compatible with the declared return type.
    • They must not call library.close() on their owning library while running.
    • They must not unregister themselves while running.

    Closing the owning library or unregistering the currently executing callback from inside the callback is unsupported and dangerous. Doing so may crash the process, produce incorrect output, or corrupt memory.

  • pointer: bigint
    ): void;

    Allows the callback to become weakly referenced by JavaScript.

    If the callback function is later garbage collected, subsequent native invocations become a no-op. Non-void return values are zero-initialized before returning to native code.

  • pointer: bigint
    ): void;

    Releases a callback previously created with library.registerCallback().

    Calling library.unregisterCallback(pointer) for a callback that is currently executing is unsupported and dangerous. The callback must return before it is unregistered.

    After library.unregisterCallback(pointer) returns, invoking that callback pointer from native code has undefined behavior, is not allowed, and is dangerous: it can crash the process, produce incorrect output, or corrupt memory.