geastack-ffi

@developersailor/geastack-ffi is a powerful library designed to facilitate the interaction between Node.js and C shared libraries, enabling seamless execution of native functions from JavaScript code. This library leverages C++ to create a lightweight host loader for various platforms, including Windows x64, Linux x64, and macOS arm64, along with support for iOS devices and Android emulators.

Key Features

• Cross-Platform Compatibility: Verified compatibility across major operating systems such as Windows, Linux, and macOS, ensuring a consistent development environment.
• Native Function Calls: Easily invoke functions from shared libraries, such as kernel32.dll on Windows, libc.so.6 on Linux, and libSystem.B.dylib on macOS, directly from TypeScript.
• Structured Memory Management: The library provides structured types and memory allocation capabilities to facilitate safe interactions with native memory.
• Comprehensive API: A straightforward API allows developers to load libraries, define and manage data structures, and create native callbacks.

Usage Examples

Windows Example

Load the kernel32.dll library and retrieve the current process ID:

import { Library, defineStruct } from '@developersailor/geastack-ffi';

const FileTime = defineStruct('FILETIME', {
  dwLowDateTime: 'uint32',
  dwHighDateTime: 'uint32',
});

const kernel32 = Library.open('kernel32.dll', {
  GetCurrentProcessId: { args: [], returns: 'uint32' },
  GetSystemTimeAsFileTime: { args: [FileTime], returns: 'void' },
});

console.log(kernel32.symbols.GetCurrentProcessId()); // Get the current process ID

const fileTime = FileTime.alloc();
kernel32.symbols.GetSystemTimeAsFileTime(fileTime);
console.log(fileTime.get('dwLowDateTime'), fileTime.get('dwHighDateTime'));
fileTime.free();
kernel32.close();

Linux Example

Load libraries and perform simple operations:

import { Library, defineStruct } from '@developersailor/geastack-ffi';

const Timeval = defineStruct('timeval', {
  tv_sec: 'int64',
  tv_usec: 'int64',
});

const libc = Library.open('libc.so.6', {
  getpid: { args: [], returns: 'int32' },
  strlen: { args: ['string'], returns: 'uint64' },
});

console.log(libc.symbols.getpid()); // Get the current process ID
console.log(libc.symbols.strlen('geastack')); // Get string length
libc.close();

Advanced Features

• Callbacks and Event Handling: Define and manage callbacks for asynchronous operations, enhancing the responsiveness of applications.
• D-Bus and Embedded Support: Advanced features enable integration with D-Bus on Linux and embedded systems, allowing for efficient communication protocols in constrained environments.
• Reusable Code: Functions can be registered and reused, facilitating a modular approach to integration with C libraries.

Limitations

While @developersailor/geastack-ffi offers significant capabilities, users should be aware of certain limitations, such as the lack of support for variadic calls without using libffi, and the requirement for certain setup conditions on macOS and Linux.

In summary, @developersailor/geastack-ffi simplifies the process of utilizing native libraries from Node.js, offering a robust and flexible solution for developers looking to enhance the performance and capabilities of their applications with seamless C integration.