FFI (Foreign Function Interface) for native code in Deno - Deep Dive

Overview - FFI (Foreign Function Interface) for native code

What is it?

FFI stands for Foreign Function Interface. It lets Deno programs call functions written in other languages like C or Rust. This means you can use fast, low-level code inside your Deno app. It works by connecting Deno to native shared libraries on your computer.

Why it matters

Without FFI, Deno would be limited to JavaScript and TypeScript code only. Many powerful system features and performance tricks live in native code. FFI lets you use these without rewriting everything in Deno. This makes apps faster and able to do more, like access hardware or optimized algorithms.

Where it fits

Before learning FFI, you should know basic Deno programming and how native libraries work. After FFI, you can explore advanced native integrations, build custom extensions, or optimize performance-critical parts of your app.

Mental Model

Core Idea

FFI is a bridge that lets Deno talk directly to native code libraries as if they were part of the program.

Think of it like...

Imagine Deno is a smartphone app, and native code is a powerful tool in a toolbox outside the phone. FFI is like a special cable that connects the phone to the toolbox, letting the app use those tools instantly.

Deno Program
  │
  ▼
[FFI Bridge]
  │
  ▼
Native Library (C, Rust, etc.)
  │
  ▼
System Hardware or OS

Build-Up - 7 Steps

1

Foundation

What is FFI and why use it

Concept: Introducing the idea of calling native code from Deno.

FFI lets Deno run functions written in other languages like C or Rust. This is useful when you need speed or access to system features not available in Deno. You load a native library and call its functions as if they were normal Deno functions.

Result

You understand that FFI connects Deno to native code, expanding what your app can do.

Understanding that Deno can reach outside its own language opens up many possibilities for performance and system access.

2

Foundation

Loading native libraries in Deno

Concept: How to load a native shared library (.dll, .so, .dylib) in Deno using FFI.

Deno provides Deno.dlopen() to load native libraries. You give it the path to the library and a description of the functions you want to call, including their argument and return types.

Result

You can load a native library and prepare to call its functions from Deno.

Knowing how to load libraries is the first step to bridging Deno with native code.

3

Intermediate

Defining function signatures for FFI

🤔Before reading on: do you think Deno automatically knows the types of native functions, or do you have to specify them? Commit to your answer.

Concept: You must tell Deno the exact types of arguments and return values for each native function.

When calling native functions, Deno needs to know the data types to convert between JavaScript and native code correctly. You define a 'symbols' object describing each function's parameters and return type using Deno's FFI type system.

Result

Deno can safely call native functions with correct data conversion.

Specifying types prevents errors and crashes by ensuring data matches between Deno and native code.

4

Intermediate

Calling native functions asynchronously

🤔Before reading on: do you think native functions called via FFI block Deno's event loop or run asynchronously? Commit to your answer.

Concept: Deno supports calling native functions asynchronously to avoid blocking the main thread.

You can mark native functions as 'async' in the symbols definition. This lets Deno run them without freezing your app, useful for long-running native operations. The call returns a Promise you can await.

Result

Your app stays responsive while waiting for native code to finish.

Knowing how to call native code asynchronously helps build smooth, non-blocking apps.

5

Intermediate

Handling pointers and buffers safely

🤔Before reading on: do you think you can pass JavaScript strings directly to native code expecting pointers, or do you need special handling? Commit to your answer.

Concept: Passing complex data like strings or buffers requires careful conversion and memory management.

Native code uses pointers to memory, but JavaScript uses objects and strings. You must convert data to ArrayBuffers or TypedArrays and manage memory manually or with helpers. This avoids crashes or data corruption.

Result

You can safely exchange complex data between Deno and native code.

Understanding memory and data formats is key to stable native integration.

6

Advanced

Managing native resources and cleanup

🤔Before reading on: do you think native resources are automatically freed when Deno finishes using them, or do you need to clean up manually? Commit to your answer.

Concept: Native code often allocates resources that Deno must release explicitly to avoid leaks.

You must call native functions to free memory or close handles when done. Deno's FFI does not automatically manage native resource lifetimes. You can use FinalizationRegistry or manual calls to clean up.

Result

Your app avoids memory leaks and crashes from unreleased native resources.

Knowing how to manage native resources prevents subtle bugs and keeps apps stable.

7

Expert

Performance and safety trade-offs in FFI

🤔Before reading on: do you think calling native code via FFI is always faster than pure Deno code? Commit to your answer.

Concept: FFI calls have overhead and risks; using them wisely is crucial for performance and safety.

Calling native code involves crossing language boundaries, which costs time. Excessive calls or large data transfers can slow your app. Also, unsafe native code can crash Deno. Experts batch calls, minimize data copying, and carefully test native code.

Result

You write efficient and safe FFI code that balances speed and reliability.

Understanding FFI overhead and risks helps you design better native integrations.

Under the Hood

Deno's FFI uses the operating system's dynamic linker to load shared libraries at runtime. It maps native functions to JavaScript callable objects by creating wrappers that convert data types between JavaScript and native memory layouts. When you call a native function, Deno marshals arguments into native format, calls the function, then converts the result back. For async calls, Deno runs the native function on a separate thread or task to avoid blocking the event loop.

Why designed this way?

This design leverages existing OS features for loading native code, avoiding reinventing linking or loading. Explicit type definitions ensure safety and correctness across language boundaries. Async support fits Deno's event-driven model. Alternatives like embedding native code directly would reduce flexibility and increase complexity. The chosen approach balances power, safety, and ease of use.

┌─────────────┐       ┌───────────────┐       ┌───────────────┐
│  Deno App   │──────▶│  FFI Wrapper  │──────▶│ Native Library│
└─────────────┘       └───────────────┘       └───────────────┘
       │                     │                        │
       │  JS values          │                        │
       │────────────────────▶│                        │
       │                     │  Native types          │
       │                     │────────────────────────▶│
       │                     │                        │
       │                     │  Native result         │
       │                     │◀────────────────────────│
       │  JS result          │                        │
       │◀────────────────────│                        │

Myth Busters - 4 Common Misconceptions

Quick: Do you think you can call any native function without specifying its argument types? Commit yes or no.

Common Belief: I can call native functions without telling Deno their argument or return types; it figures it out automatically.

Reality: You must explicitly define all argument and return types for each native function in Deno's FFI. Without this, calls will fail or cause crashes.

Why it matters: Skipping type definitions leads to incorrect data conversion, causing crashes or corrupted data that are hard to debug.

Quick: Do you think native functions called via FFI always run asynchronously? Commit yes or no.

Common Belief: All native functions called through FFI run asynchronously and never block the Deno event loop.

Reality: By default, native functions run synchronously and block the event loop unless explicitly marked as async.

Why it matters: Assuming async behavior can cause your app to freeze unexpectedly, harming user experience.

Quick: Do you think Deno automatically frees memory allocated by native code? Commit yes or no.

Common Belief: Deno automatically manages and frees all memory used by native code called via FFI.

Reality: Deno does not manage native memory; you must manually free any memory allocated by native functions.

Why it matters: Failing to free native memory causes leaks that degrade performance and can crash your app.

Quick: Do you think calling native code via FFI is always faster than JavaScript? Commit yes or no.

Common Belief: Calling native code through FFI is always faster than running equivalent JavaScript code.

Reality: FFI calls have overhead; small or frequent calls can be slower than pure JavaScript.

Why it matters: Misusing FFI for trivial tasks can reduce performance instead of improving it.

Expert Zone

1

FFI calls cross language boundaries, so minimizing call frequency and batching data reduces overhead significantly.

2

Memory alignment and data layout differences between JavaScript and native code can cause subtle bugs if not handled carefully.

3

Using FinalizationRegistry to clean up native resources can prevent leaks but requires careful design to avoid premature cleanup.

When NOT to use

Avoid FFI for simple logic that JavaScript can handle efficiently. Use it mainly for performance-critical code or system-level access. Alternatives include WebAssembly for portable native code or Deno plugins for more complex native extensions.

Production Patterns

In production, FFI is used to integrate optimized C libraries for cryptography, image processing, or hardware access. Developers wrap native calls in safe JavaScript APIs, handle errors carefully, and automate resource cleanup to ensure stability.

Connections

WebAssembly

Alternative approach to running native-like code in Deno

Understanding FFI helps appreciate when to use WebAssembly for portable, sandboxed native code versus direct native calls.

Operating System Dynamic Linking

FFI relies on OS dynamic linking to load native libraries at runtime

Knowing how OS loaders work clarifies how FFI finds and connects to native functions.

Foreign Language Interoperability in Compilers

FFI is a practical example of language interoperability concepts in compiler design

Seeing FFI in action deepens understanding of how different languages can communicate and share data safely.

Common Pitfalls

#1 Calling native functions without specifying correct argument types

Wrong approach:

const lib = Deno.dlopen("./lib.so", { add: { parameters: ["i32"], result: "i32" } });
lib.symbols.add(1, 2); // Missing second parameter type

Correct approach:

const lib = Deno.dlopen("./lib.so", { add: { parameters: ["i32", "i32"], result: "i32" } });
lib.symbols.add(1, 2);

Root cause:

Misunderstanding that all parameter types must be declared exactly to match the native function signature.

#2 Passing JavaScript strings directly to native functions expecting pointers

Wrong approach:

lib.symbols.printString("hello world"); // Passing JS string directly

Correct approach:

const encoder = new TextEncoder();
const buf = encoder.encode("hello world");
lib.symbols.printString(buf); // Pass ArrayBuffer or pointer

Root cause:

Not realizing native code expects pointers to memory, not JavaScript string objects.

#3 Not freeing native memory allocated during FFI calls

Wrong approach:

const ptr = lib.symbols.allocateBuffer(100);
// Use ptr but never free it

Correct approach:

const ptr = lib.symbols.allocateBuffer(100);
// Use ptr
lib.symbols.freeBuffer(ptr);

Root cause:

Assuming Deno's garbage collector manages native memory, which it does not.

Key Takeaways

FFI lets Deno call native code by loading shared libraries and defining function signatures.

You must specify argument and return types precisely to ensure safe and correct calls.

Handling memory and data conversion between JavaScript and native code is critical to avoid crashes.

Native calls can be synchronous or asynchronous; using async calls keeps your app responsive.

FFI has overhead and risks; use it wisely for performance-critical or system-level tasks only.

Practice

1. What is the main purpose of using Deno.dlopen in Deno's FFI?

easy

A. To load a native shared library and access its functions

B. To compile TypeScript code into JavaScript

C. To start a web server in Deno

D. To read files from the filesystem

Solution

1. Step 1: Understand the role of Deno.dlopen

   Deno.dlopen is used to load native shared libraries (like .dll, .so, .dylib) so Deno can call native functions.

2. Step 2: Compare with other options

   Options B, C, and D relate to other Deno features but not FFI or native code loading.

3. Final Answer:

   To load a native shared library and access its functions -> Option A

4. Quick Check:

   Deno.dlopen loads native libraries = A [OK]

Hint: Remember: dlopen means 'dynamic library open' [OK]

Common Mistakes:

• Confusing dlopen with file reading functions
• Thinking dlopen compiles code
• Mixing up server start with FFI loading

2. Which of the following is the correct way to define a function signature for a native function returning an integer in Deno.dlopen?

easy

A. { myFunc: { parameters: ["i32"], result: "void" } }

B. { myFunc: { parameters: ["i32"], result: "i32" } }

C. { myFunc: { parameters: ["void"], result: "i32" } }

D. { myFunc: { parameters: [], result: "string" } }

Solution

1. Step 1: Understand function signature format

   Function signatures in Deno.dlopen require specifying parameter types and the return type. For a function taking an integer and returning an integer, both parameters and result should be "i32".

2. Step 2: Analyze each option

   { myFunc: { parameters: ["i32"], result: "void" } } returns void, not integer. { myFunc: { parameters: ["void"], result: "i32" } } has parameters as void which is invalid. { myFunc: { parameters: [], result: "string" } } returns string but parameters are empty. Only { myFunc: { parameters: ["i32"], result: "i32" } } correctly matches integer parameter and integer return.

3. Final Answer:

   { myFunc: { parameters: ["i32"], result: "i32" } } -> Option B

4. Quick Check:

   Integer parameter and return = C [OK]

Hint: Match parameter and result types exactly as strings [OK]

Common Mistakes:

• Using 'void' as a parameter type incorrectly
• Mixing return and parameter types
• Using unsupported types like 'string' without proper handling

3. Given the following code snippet, what will be the output?

const lib = Deno.dlopen("./libmath.so", {
  add: { parameters: ["i32", "i32"], result: "i32" }
});

const result = lib.symbols.add(10, 5);
console.log(result);
lib.close();

medium

A. undefined

B. 105

C. 15

D. Runtime error

Solution

1. Step 1: Understand the function signature and call

   The native function 'add' takes two 32-bit integers and returns a 32-bit integer. Calling add(10, 5) should return 15.

2. Step 2: Analyze the output

   The console.log prints the returned value, which is 15. No errors occur because the signature matches and the library is closed properly.

3. Final Answer:

   15 -> Option C

4. Quick Check:

   Adding 10 + 5 = 15 [OK]

Hint: Check parameter types and expected return for output [OK]

Common Mistakes:

• Concatenating numbers as strings (getting 105)
• Forgetting to close the library
• Assuming undefined return without checking signature

4. Identify the error in this Deno FFI code snippet:

const lib = Deno.dlopen("./libcalc.so", {
  multiply: { parameters: ["i32", "i32"], result: "i64" }
});

const output = lib.symbols.multiply(3, 4);
console.log(output);
lib.close();

medium

A. The result type should be "i32" instead of "i64"

B. The parameters array should be empty

C. The library path is incorrect

D. The function call syntax is invalid

Solution

1. Step 1: Check function signature consistency

   The function 'multiply' takes two 32-bit integers and likely returns a 32-bit integer. Using "i64" as result type can cause mismatch errors if the native function returns 32-bit.

2. Step 2: Validate other parts

   Parameters are correctly specified as two "i32". The library path and function call syntax are valid assuming the file exists and function is exported.

3. Final Answer:

   The result type should be "i32" instead of "i64" -> Option A

4. Quick Check:

   Result type must match native function = D [OK]

Hint: Match return type exactly with native function signature [OK]

Common Mistakes:

• Changing parameter types incorrectly
• Assuming library path error without checking
• Misusing function call syntax

5. You want to call a native function that returns a pointer to a UTF-8 string. Which approach correctly handles this in Deno FFI?

hard

A. Define the function with result type "string" and use it directly

B. Define the function with result type "i32" and convert to string

C. Define the function with result type "void" and cast the result to string

D. Define the function with result type "pointer", then use Deno.UnsafePointerView to read the string

Solution

1. Step 1: Understand pointer return handling

   Native functions returning strings usually return pointers. Deno FFI requires defining the result as "pointer" to get the address.

2. Step 2: Use Deno.UnsafePointerView to read UTF-8

   After getting the pointer, Deno.UnsafePointerView can read the memory as a UTF-8 string safely.

3. Final Answer:

   Define the function with result type "pointer", then use Deno.UnsafePointerView to read the string -> Option D

4. Quick Check:

   Pointer + UnsafePointerView for strings = B [OK]

Hint: Use pointer type and UnsafePointerView for native strings [OK]

Common Mistakes:

• Using 'string' as result type directly
• Casting void or integer to string incorrectly
• Ignoring memory safety when reading pointers