@entelligentsia/forgecli 0.15.0 → 0.20.0

package/node_modules/koffi/doc/functions.md

@@ -1,250 +0,0 @@
-# Loading libraries
-
-To declare functions, start by loading the shared library with `koffi.load(filename)`.
-
-```js
-// ES6 syntax: import koffi from 'koffi';
-const koffi = require('koffi');
-
-const lib = koffi.load('/path/to/shared/library'); // File extension depends on platforms: .so, .dll, .dylib, etc.
-```
-
-This library will be automatically unloaded once all references to it are gone (including all the functions that use it, as described below).
-
-Starting with *Koffi 2.3.20*, you can explicitly unload a library by calling `lib.unload()`. Any attempt to find or call a function from this library after unloading it will crash.
-
-> [!NOTE]
-> On some platforms (such as with the [musl C library on Linux](https://wiki.musl-libc.org/functional-differences-from-glibc.html#Unloading-libraries)), shared libraries cannot be unloaded, so the library will remain loaded and memory mapped after the call to `lib.unload()`.
-
-# Loading options
-
-*New in Koffi 2.6, changed in Koffi 2.8.2 and Koffi 2.8.6*
-
-The `load` function can take an optional object argument, with the following options:
-
-```js
-const options = {
-    lazy: true, // Use RTLD_LAZY (lazy-binding) on POSIX platforms (by default, use RTLD_NOW)
-    global: true, // Use RTLD_GLOBAL on POSIX platforms (by default, use RTLD_LOCAL)
-    deep: true // Use RTLD_DEEPBIND if supported (Linux, FreeBSD)
-};
-
-const lib = koffi.load('/path/to/shared/library.so', options);
-```
-
-More options may be added if needed.
-
-# Function definitions
-
-## Definition syntax
-
-Use the object returned by `koffi.load()` to load C functions from the library. To do so, you can use two syntaxes:
-
-- The classic syntax, inspired by node-ffi
-- C-like prototypes
-
-### Classic syntax
-
-To declare a function, you need to specify its non-mangled name, its return type, and its parameters. Use an ellipsis as the last parameter for variadic functions.
-
-```js
-const printf = lib.func('printf', 'int', ['str', '...']);
-const atoi = lib.func('atoi', 'int', ['str']);
-```
-
-Koffi automatically tries mangled names for non-standard x86 calling conventions. See the section on [calling conventions](#calling-conventions) for more information on this subject.
-
-### C-like prototypes
-
-If you prefer, you can declare functions using simple C-like prototype strings, as shown below:
-
-```js
-const printf = lib.func('int printf(const char *fmt, ...)');
-const atoi = lib.func('int atoi(str)'); // The parameter name is not used by Koffi, and optional
-```
-
-You can use `()` or `(void)` for functions that take no argument.
-
-## Variadic functions
-
-Variadic functions are declared with an ellipsis as the last argument.
-
-In order to call a variadic function, you must provide two Javascript arguments for each additional C parameter, the first one is the expected type and the second one is the value.
-
-```js
-const printf = lib.func('printf', 'int', ['str', '...']);
-
-// The variadic arguments are: 6 (int), 8.5 (double), 'THE END' (const char *)
-printf('Integer %d, double %g, str %s', 'int', 6, 'double', 8.5, 'str', 'THE END');
-```
-
-On x86 platforms, only the Cdecl convention can be used for variadic functions.
-
-## Calling conventions
-
-*Changed in Koffi 2.7*
-
-By default, calling a C function happens synchronously.
-
-Most architectures only support one procedure call standard per process. The 32-bit x86 platform is an exception to this, and Koffi supports several x86 conventions:
-
- Convention   | Classic form                                  | Prototype form | Description
-------------- | --------------------------------------------- | -------------- | -------------------------------------------------------------------
- **Cdecl**    | `koffi.func(name, ret, params)`               | _(default)_    | This is the default convention, and the only one on other platforms
- **Stdcall**  | `koffi.func('__stdcall', name, ret, params)`  | __stdcall      | This convention is used extensively within the Win32 API
- **Fastcall** | `koffi.func('__fastcall', name, ret, params)` | __fastcall     | Rarely used, uses ECX and EDX for first two parameters
- **Thiscall** | `koffi.func('__thiscall', name, ret, params)` | __thiscall     | Rarely used, uses ECX for first parameter
-
-You can safely use these on non-x86 platforms, they are simply ignored.
-
-> [!NOTE]
-> Support for specifying the convention as the first argument of the classic form was introduced in Koffi 2.7.
->
-> In earlier versions, you had to use `koffi.stdcall()` and similar functions. These functions are still supported but deprecated, and will be removed in Koffi 3.0.
-
-Below you can find a small example showing how to use a non-default calling convention, with the two syntaxes:
-
-```js
-// ES6 syntax: import koffi from 'koffi';
-const koffi = require('koffi');
-
-const lib = koffi.load('user32.dll');
-
-// The following two declarations are equivalent, and use stdcall on x86 (and the default ABI on other platforms)
-const MessageBoxA_1 = lib.func('__stdcall', 'MessageBoxA', 'int', ['void *', 'str', 'str', 'uint']);
-const MessageBoxA_2 = lib.func('int __stdcall MessageBoxA(void *hwnd, str text, str caption, uint type)');
-```
-
-# Call types
-
-## Synchronous calls
-
-Once a native function has been declared, you can simply call it as you would any other JS function.
-
-```js
-const atoi = lib.func('int atoi(const char *str)');
-
-let value = atoi('1257');
-console.log(value);
-```
-
-For [variadic functions](functions#variadic-functions), you msut specificy the type and the value for each additional argument.
-
-```js
-const printf = lib.func('printf', 'int', ['str', '...']);
-
-// The variadic arguments are: 6 (int), 8.5 (double), 'THE END' (const char *)
-printf('Integer %d, double %g, str %s', 'int', 6, 'double', 8.5, 'str', 'THE END');
-```
-
-## Asynchronous calls
-
-You can issue asynchronous calls by calling the function through its async member. In this case, you need to provide a callback function as the last argument, with `(err, res)` parameters.
-
-```js
-// ES6 syntax: import koffi from 'koffi';
-const koffi = require('koffi');
-
-const lib = koffi.load('libc.so.6');
-
-const atoi = lib.func('int atoi(const char *str)');
-
-atoi.async('1257', (err, res) => {
-    console.log('Result:', res);
-})
-console.log('Hello World!');
-
-// This program will print:
-//   Hello World!
-//   Result: 1257
-```
-
-These calls are executed by worker threads. It is **your responsibility to deal with data sharing issues** in the native code that may be caused by multi-threading.
-
-You can easily convert this callback-style async function to a promise-based version with `util.promisify()` from the Node.js standard library.
-
-Variadic functions cannot be called asynchronously.
-
-> [!WARNING]
-> Asynchronous functions run on worker threads. You need to deal with thread safety issues if you share data between threads.
->
-> Callbacks must be called from the main thread, or more precisely from the same thread as the V8 intepreter. Calling a callback from another thread is undefined behavior, and will likely lead to a crash or a big mess. You've been warned!
-
-# Function pointers
-
-*New in Koffi 2.4*
-
-You can call a function pointer in two ways:
-
-- Directly call the function pointer with `koffi.call(ptr, type, ...)`
-- Decode the function pointer to an actual function with `koffi.decode(ptr, type)`
-
-The example below shows how to call an `int (*)(int, int)` C function pointer both ways, based on the following native C library:
-
-```c
-typedef int BinaryIntFunc(int a, int b);
-
-static int AddInt(int a, int b) { return a + b; }
-static int SubstractInt(int a, int b) { return a - b; }
-
-BinaryIntFunc *GetBinaryIntFunction(const char *type)
-{
-    if (!strcmp(type, "add")) {
-        return AddInt;
-    } else if (!strcmp(type, "substract")) {
-        return SubstractInt;
-    } else {
-        return NULL;
-    }
-}
-```
-
-## Call pointer directly
-
-Use `koffi.call(ptr, type, ...)` to call a function pointer. The first two arguments are the pointer itself and the type of the function you are trying to call (declared with `koffi.proto()` as shown below), and the remaining arguments are used for the call.
-
-```js
-// Declare function type
-const BinaryIntFunc = koffi.proto('int BinaryIntFunc(int a, int b)');
-
-const GetBinaryIntFunction = lib.func('BinaryIntFunc *GetBinaryIntFunction(const char *name)');
-
-const add_ptr = GetBinaryIntFunction('add');
-const substract_ptr = GetBinaryIntFunction('substract');
-
-let sum = koffi.call(add_ptr, BinaryIntFunc, 4, 5);
-let delta = koffi.call(substract_ptr, BinaryIntFunc, 100, 58);
-
-console.log(sum, delta); // Prints 9 and 42
-```
-
-## Decode pointer to function
-
-Use `koffi.decode(ptr, type)` to get back a JS function, which you can then use like any other Koffi function.
-
-This method also allows you to perform an [asynchronous call](#asynchronous-calls) with the async member of the decoded function.
-
-```js
-// Declare function type
-const BinaryIntFunc = koffi.proto('int BinaryIntFunc(int a, int b)');
-
-const GetBinaryIntFunction = lib.func('BinaryIntFunc *GetBinaryIntFunction(const char *name)');
-
-const add = koffi.decode(GetBinaryIntFunction('add'), BinaryIntFunc);
-const substract = koffi.decode(GetBinaryIntFunction('substract'), BinaryIntFunc);
-
-let sum = add(4, 5);
-let delta = substract(100, 58);
-
-console.log(sum, delta); // Prints 9 and 42
-```
-
-# Conversion of parameters
-
-By default, Koffi will only forward and translate arguments from Javascript to C. However, many C functions use pointer arguments for output values, or input/output values.
-
-Among other thing, in the the following pages you will learn more about:
-
-- How Koffi translates [input parameters](input) to C
-- How you can [define and use pointers](pointers)
-- How to deal with [output parameters](output)

package/node_modules/koffi/doc/index.md

@@ -1,61 +0,0 @@
-# Overview
-
-Koffi is a **fast and easy-to-use C FFI module for Node.js**, featuring:
-
-* Low-overhead and fast performance (see [benchmarks](benchmarks))
-* Support for primitive and aggregate data types (structs and fixed-size arrays), both by reference (pointer) and by value
-* Javascript functions can be used as C callbacks
-* Well-tested code base for popular OS/architecture combinations
-
-If you like this project, consider supporting me:
-
-<p style="display: flex; gap: 1em; justify-content: center; align-items: center;">
-     <a href="https://liberapay.com/Koromix/donate" target="_blank"><img alt="Donate using Liberapay" src="https://liberapay.com/assets/widgets/donate.svg"></a>
-     <a href="https://github.com/sponsors/koromix" target="_blank"><img src="https://img.shields.io/static/v1?label=Sponsor&message=%E2%9D%A4&logo=GitHub&color=%23fe8e86"></a>
-     <a href="https://buymeacoffee.com/koromix" target="_blank"><img src="https://cdn.buymeacoffee.com/buttons/default-yellow.png" alt="Buy Me A Coffee" height="30" width="108" style="border-radius: 12px;"></a>
-</p>
-
-Koffi requires [Node.js](https://nodejs.org/) version 16 or later. Use [NVM](https://github.com/nvm-sh/nvm) to install more recent Node versions on older Linux distributions.
-
-The following combinations of OS and architectures __are officially supported and tested__ at the moment:
-
-ISA / OS           | Windows | Linux (glibc) | Linux (musl) | macOS | FreeBSD | OpenBSD
------------------- | ------- | ------------- | ------------ | ----- | ------- | -------
-x86 (IA32) [^2]    | ✅       | ✅             | 🟨            | ⬜️    | ✅       | ✅
-x86_64 (AMD64)     | ✅       | ✅             | ✅            | ✅    | ✅       | ✅
-ARM32 LE [^3]      | ⬜️       | ✅             | 🟨            | ⬜️    | 🟨       | 🟨
-ARM64 (AArch64) LE | ✅       | ✅             | ✅            | ✅    | ✅       | 🟨
-RISC-V 64 [^4]     | ⬜️       | ✅             | 🟨            | ⬜️    | 🟨       | 🟨
-LoongArch64        | ⬜️       | ✅             | 🟨            | ⬜️    | 🟨       | 🟨
-
-<div class="legend">✅ Yes | 🟨 Probably | ⬜️ Not applicable</div>
-
-[^2]: The following call conventions are supported for forward calls: cdecl, stdcall, MS fastcall, thiscall. Only cdecl and stdcall can be used for C to JS callbacks.
-[^3]: The prebuilt binary uses the hard float ABI and expects a VFP coprocessor. Build from source to use Koffi with a different ABI (softfp, soft).
-[^4]: The prebuilt binary uses the LP64D (double-precision float) ABI. The LP64 ABI is supported in theory if you build Koffi from source (untested), the LP64F ABI is not supported.
-
-For all fully supported platforms (green check marks), a prebuilt binary is included in the NPM package which means you can install Koffi without a C++ compiler.
-
-# Source code
-
-The source code is available here: https://github.com/Koromix/rygel/ (in the *src/koffi* subdirectory).
-
-> [!NOTE]
-> Most of my projects live in a single repository (or monorepo), which have two killer features for me:
->
-> - Cross-project refactoring
-> - Simplified dependency management
->
-> You can find a more detailed rationale here: https://danluu.com/monorepo/
-
-New releases are frequent, look at the [changelog](changelog) for more information.
-
-# License
-
-This program is free software: you can redistribute it and/or modify it under the terms of the **MIT License**.
-
-Find more information here: https://choosealicense.com/licenses/mit/
-
-<style>
-     table td:not(:first-child) { text-align: center; }
-</style>