@sng2c/pi-the-giver 0.1.0 → 0.1.1

package/node_modules/koffi/doc/misc.md

@@ -0,0 +1,180 @@
+# Types
+
+## Introspection
+
+*New in Koffi 2.0: `koffi.resolve()`, new in Koffi 2.2: `koffi.offsetof()`*
+
+> [!NOTE]
+> The value returned by `introspect()` has **changed in version 2.0 and in version 2.2**.
+>
+> In Koffi 1.x, it could only be used with struct types and returned the object passed to koffi.struct() with the member names and types.
+>
+> Starting in Koffi 2.2, each record member is exposed as an object containing the name, the type and the offset within the record.
+>
+> Consult the [migration guide](migration) for more information.
+
+Use `koffi.introspect(type)` to get detailed information about a type: name, primitive, size, alignment, members (record types), reference type (array, pointer) and length (array).
+
+```js
+const FoobarType = koffi.struct('FoobarType', {
+    a: 'int',
+    b: 'char *',
+    c: 'double'
+});
+
+console.log(koffi.introspect(FoobarType));
+
+// Expected result on 64-bit machines:
+// {
+//     name: 'FoobarType',
+//     primitive: 'Record',
+//     size: 24,
+//     alignment: 8,
+//     members: {
+//         a: { name: 'a', type: [External: 4b28a60], offset: 0 },
+//         b: { name: 'b', type: [External: 4b292e0], offset: 8 },
+//         c: { name: 'c', type: [External: 4b29260], offset: 16 }
+//     }
+// }
+```
+
+Koffi also exposes a few more utility functions to get a subset of this information:
+
+- `koffi.sizeof(type)` to get the size of a type
+- `koffi.alignof(type)` to get the alignment of a type
+- `koffi.offsetof(type, member_name)` to get the offset of a record member
+- `koffi.resolve(type)` to get the resolved type object from a type string
+
+Just like before, you can refer to primitive types by their name or through `koffi.types`:
+
+```js
+// These two lines do the same:
+console.log(koffi.sizeof('long'));
+console.log(koffi.sizeof(koffi.types.long));
+```
+
+## Aliases
+
+*New in Koffi 2.0*
+
+You can alias a type with `koffi.alias(name, type)`. Aliased types are completely equivalent.
+
+## Circular references
+
+*New in Koffi 2.10.0*
+
+In some cases, composite types can point to each other and thus depend on each other. This can also happen when a function takes a pointer to a struct that also contains a function pointer.
+
+To deal with this, you can create an opaque type and redefine it later to a concrete struct or union type, as shown below.
+
+```js
+const Type1 = koffi.opaque('Type1');
+
+const Type2 = koffi.struct('Type2', {
+    ptr: 'Type1 *',
+    i: 'int'
+});
+
+// Redefine Type1 to a concrete type
+koffi.struct(Type1, {
+    ptr: 'Type2 *',
+    f: 'float'
+});
+```
+
+> [!NOTE]
+> You must use a proper type object when you redefine the type. If you only have the name, use `koffi.resolve()` to get a type object from a type string.
+>
+> ```js
+> const MyType = koffi.opaque('MyType');
+>
+> // This does not work, you must use the MyType object and not a type string
+> koffi.struct('MyType', {
+>      ptr: 'Type2 *',
+>      f: 'float'
+> });
+
+# Settings
+
+## Memory usage
+
+For synchronous/normal calls, Koffi uses two preallocated memory blocks:
+
+- One to construct the C stack and assign registers, subsequently used by the platform-specific assembly code (1 MiB by default)
+- One to allocate strings and objects/structs (2 MiB by default)
+
+Unless very big strings or objects (at least more than one page of memory) are used, Koffi does not directly allocate any extra memory during calls or callbacks. However, please note that the JS engine (V8) might.
+
+The size (in bytes) of these preallocated blocks can be changed. Use `koffi.config()` to get an object with the settings, and `koffi.config(obj)` to apply new settings.
+
+```js
+let config = koffi.config();
+console.log(config);
+```
+
+The same is true for asynchronous calls. When an asynchronous call is made, Koffi will allocate new blocks unless there is an unused (resident) set of blocks still available. Once the asynchronous call is finished, these blocks are freed if there are more than `resident_async_pools` sets of blocks left around. By default, the preallocated stack and heap blocks are much smaller than for synchronous calls (see [default settings](#default-settings)).
+
+> [!CAUTION]
+> The **memory usage can blow up easily** if you increase the size of async memory blocks and many async calls are running or queued at the same time !
+>
+> For example, with 4096 running/queued async calls, a stack size of 256 kiB and a heap size of 512 kiB, the memory usage will reach approximately _4096 * (256 + 512) kiB ≈ 3 GiB_ just for Koffi, even though most of it will be freed once the number of queued calls goes down.
+
+Async calls run on worker threads, the number of which depends on the number of cores in your machine. Additional async calls are queued, up to `max_async_calls` can run and be queued at the same time. If you try to make an async call once the queue if full, an exception will be thrown.
+
+## Default settings
+
+*Changed in Koffi 2.15*
+
+Setting              | Default | Maximum | Description
+-------------------- | ------- | ------- | ----------------------------------------------------
+sync_stack_size      | 1 MiB   | 16 MiB  | Stack size for synchronous calls
+sync_heap_size       | 2 MiB   | 16 MiB  | Heap size for synchronous calls
+async_stack_size     | 128 kiB | 16 MiB  | Stack size for asynchronous calls
+async_heap_size      | 128 kiB | 16 MiB  | Heap size for asynchronous calls
+resident_async_pools | 4       | 16      | Number of resident pools for asynchronous calls
+max_async_calls      | 256     | 4096    | Maximum number of queued asynchronous calls
+max_type_size        | 64 MiB  | 512 MiB | Maximum size of Koffi types (for arrays and structs)
+
+# Usage statistics
+
+*New in Koffi 2.3.2*
+
+You can use `koffi.stats()` to get a few statistics related to Koffi.
+
+# POSIX error codes
+
+*New in Koffi 2.3.14*
+
+You can use `koffi.errno()` to get the current errno value, and `koffi.errno(value)` to change it.
+
+The standard POSIX error codes are available in `koffi.os.errno`, as shown below:
+
+```js
+const assert = require('assert');
+
+// ES6 syntax: import koffi from 'koffi';
+const koffi = require('koffi');
+
+const lib = koffi.load('libc.so.6');
+
+const close = lib.func('int close(int fd)');
+
+close(-1);
+assert.equal(koffi.errno(), koffi.os.errno.EBADF);
+
+console.log('close() with invalid FD is POSIX compliant!');
+```
+
+# Reset internal state
+
+*New in Koffi 2.5.19*
+
+You can use `koffi.reset()` to clear some Koffi internal state such as:
+
+- Parser type names
+- Asynchronous function broker (useful to avoid false positive with `jest --detectOpenHandles`)
+
+This function is mainly intended for test code, when you execute the same code over and over and you need to reuse type names.
+
+> [!WARNING]
+> Trying to use a function or a type that was initially defined before the reset is undefined behavior and will likely lead to a crash!

package/node_modules/koffi/doc/output.md

@@ -0,0 +1,305 @@
+# Output and input/output
+
+For simplicity, and because Javascript only has value semantics for primitive types, Koffi can marshal out (or in/out) multiple types of parameters:
+
+- [Structs](input#struct-types) (to/from JS objects)
+- [Unions](unions)
+- [Opaque types](input#opaque-types)
+- String buffers
+
+In order to change an argument from input-only to output or input/output, use the following functions:
+
+- `koffi.out()` on a pointer, e.g. `koffi.out(koffi.pointer(timeval))` (where timeval is a struct type)
+- `koffi.inout()` for dual input/output parameters
+
+The same can be done when declaring a function with a C-like prototype string, with the MSDN-like type qualifiers:
+
+- `_Out_` for output parameters
+- `_Inout_` for dual input/output parameters
+
+> [!TIP]
+> The Win32 API provides many functions that take a pointer to an empty struct for output, except that the first member of the struct (often named `cbSize`) must be set to the size of the struct before calling the function. An example of such a function is `GetLastInputInfo()`.
+>
+> In order to use these functions in Koffi, you must define the parameter as `_Inout_`: the value must be copied in (to provide `cbSize` to the function) and then the filled struct must be copied out to JS.
+>
+> Look at the [Win32 example](#win32-struct-example) below for more information.
+
+## Primitive value
+
+This Windows example enumerate all Chrome windows along with their PID and their title. The `GetWindowThreadProcessId()` function illustrates how to get a primitive value from an output argument.
+
+```js
+// ES6 syntax: import koffi from 'koffi';
+const koffi = require('koffi');
+
+const user32 = koffi.load('user32.dll');
+
+const DWORD = koffi.alias('DWORD', 'uint32_t');
+const HANDLE = koffi.pointer('HANDLE', koffi.opaque());
+const HWND = koffi.alias('HWND', HANDLE);
+
+const FindWindowEx = user32.func('HWND __stdcall FindWindowExW(HWND hWndParent, HWND hWndChildAfter, const char16_t *lpszClass, const char16_t *lpszWindow)');
+const GetWindowThreadProcessId = user32.func('DWORD __stdcall GetWindowThreadProcessId(HWND hWnd, _Out_ DWORD *lpdwProcessId)');
+const GetWindowText = user32.func('int __stdcall GetWindowTextA(HWND hWnd, _Out_ uint8_t *lpString, int nMaxCount)');
+
+for (let hwnd = null;;) {
+    hwnd = FindWindowEx(0, hwnd, 'Chrome_WidgetWin_1', null);
+
+    if (!hwnd)
+        break;
+
+    // Get PID
+    let pid;
+    {
+        let ptr = [null];
+        let tid = GetWindowThreadProcessId(hwnd, ptr);
+
+        if (!tid) {
+            // Maybe the process ended in-between?
+            continue;
+        }
+
+        pid = ptr[0];
+    }
+
+    // Get window title
+    let title;
+    {
+        let buf = Buffer.allocUnsafe(1024);
+        let length = GetWindowText(hwnd, buf, buf.length);
+
+        if (!length) {
+            // Maybe the process ended in-between?
+            continue;
+        }
+
+        title = koffi.decode(buf, 'char', length);
+    }
+
+    console.log({ PID: pid, Title: title });
+}
+```
+
+## Struct examples
+
+### POSIX struct example
+
+This example calls the POSIX function `gettimeofday()`, and uses the prototype-like syntax.
+
+```js
+// ES6 syntax: import koffi from 'koffi';
+const koffi = require('koffi');
+
+const lib = koffi.load('libc.so.6');
+
+const timeval = koffi.struct('timeval', {
+    tv_sec: 'unsigned int',
+    tv_usec: 'unsigned int'
+});
+const timezone = koffi.struct('timezone', {
+    tz_minuteswest: 'int',
+    tz_dsttime: 'int'
+});
+
+// The _Out_ qualifiers instruct Koffi to marshal out the values
+const gettimeofday = lib.func('int gettimeofday(_Out_ timeval *tv, _Out_ timezone *tz)');
+
+let tv = {};
+gettimeofday(tv, null);
+
+console.log(tv);
+```
+
+### Win32 struct example
+
+Many Win32 functions that use struct outputs require you to set a size member (often named `cbSize`). These functions won't work with `_Out_` because the size value must be copied from JS to C, use `_Inout_` in this case.
+
+```js
+// ES6 syntax: import koffi from 'koffi';
+const koffi = require('koffi');
+
+const user32 = koffi.load('user32.dll');
+
+const LASTINPUTINFO = koffi.struct('LASTINPUTINFO', {
+    cbSize: 'uint',
+    dwTime: 'uint32'
+});
+const GetLastInputInfo = user32.func('bool __stdcall GetLastInputInfo(_Inout_ LASTINPUTINFO *plii)');
+
+let info = { cbSize: koffi.sizeof(LASTINPUTINFO) };
+let success = GetLastInputInfo(info);
+
+console.log(success, info);
+```
+
+## Opaque type example
+
+This example opens an in-memory SQLite database, and uses the node-ffi-style function declaration syntax.
+
+```js
+// ES6 syntax: import koffi from 'koffi';
+const koffi = require('koffi');
+
+const lib = koffi.load('sqlite3.so');
+
+const sqlite3 = koffi.opaque('sqlite3');
+
+// Use koffi.out() on a double pointer to copy out (from C to JS) after the call
+const sqlite3_open_v2 = lib.func('sqlite3_open_v2', 'int', ['str', koffi.out(koffi.pointer(sqlite3, 2)), 'int', 'str']);
+const sqlite3_close_v2 = lib.func('sqlite3_close_v2', 'int', [koffi.pointer(sqlite3)]);
+
+const SQLITE_OPEN_READWRITE = 0x2;
+const SQLITE_OPEN_CREATE = 0x4;
+
+let out = [null];
+if (sqlite3_open_v2(':memory:', out, SQLITE_OPEN_READWRITE | SQLITE_OPEN_CREATE, null) != 0)
+    throw new Error('Failed to open database');
+let db = out[0];
+
+sqlite3_close_v2(db);
+```
+
+## String buffer example
+
+*New in Koffi 2.2*
+
+This example calls a C function to concatenate two strings to a pre-allocated string buffer. Since JS strings are immutable, you must pass an array with a single string instead.
+
+```c
+void ConcatToBuffer(const char *str1, const char *str2, char *out)
+{
+    size_t len = 0;
+
+    for (size_t i = 0; str1[i]; i++) {
+        out[len++] = str1[i];
+    }
+    for (size_t i = 0; str2[i]; i++) {
+        out[len++] = str2[i];
+    }
+
+    out[len] = 0;
+}
+```
+
+```js
+const ConcatToBuffer = lib.func('void ConcatToBuffer(const char *str1, const char *str2, _Out_ char *out)');
+
+let str1 = 'Hello ';
+let str2 = 'Friends!';
+
+// We need to reserve space for the output buffer! Including the NUL terminator
+// because ConcatToBuffer() expects so, but Koffi can convert back to a JS string
+// without it (if we reserve the right size).
+let out = ['\0'.repeat(str1.length + str2.length + 1)];
+
+ConcatToBuffer(str1, str2, out);
+
+console.log(out[0]);
+```
+
+# Output buffers
+
+In most cases, you can use buffers and typed arrays to provide output buffers. This works as long as the buffer only gets used while the native C function is being called. See [transient pointers](#transient-pointers) below for an example.
+
+> [!WARNING]
+> It is unsafe to keep the pointer around in the native code, or to change the contents outside of the function call where it is provided.
+>
+> If you need to provide a pointer that will be kept around, allocate memory with [koffi.alloc()](#stable-pointers) instead.
+
+## Transient pointers
+
+*New in Koffi 2.3*
+
+You can use buffers and typed arrays for output (and input/output) pointer parameters. Simply pass the buffer as an argument and the native function will receive a pointer to its contents.
+
+Once the native function returns, you can decode the content with `koffi.decode(value, type)` as in the following example:
+
+```js
+// ES6 syntax: import koffi from 'koffi';
+const koffi = require('koffi');
+
+const lib = koffi.load('libc.so.6');
+
+const Vec3 = koffi.struct('Vec3', {
+    x: 'float32',
+    y: 'float32',
+    z: 'float32'
+})
+
+const memcpy = lib.func('void *memcpy(_Out_ void *dest, const void *src, size_t size)');
+
+let vec1 = { x: 1, y: 2, z: 3 };
+let vec2 = null;
+
+// Copy the vector in a convoluted way through memcpy
+{
+    let src = koffi.as(vec1, 'Vec3 *');
+    let dest = Buffer.allocUnsafe(koffi.sizeof(Vec3));
+
+    memcpy(dest, src, koffi.sizeof(Vec3));
+
+    vec2 = koffi.decode(dest, Vec3);
+}
+
+// CHange vector1, leaving copy alone
+[vec1.x, vec1.y, vec1.z] = [vec1.z, vec1.y, vec1.x];
+
+console.log(vec1); // { x: 3, y: 2, z: 1 }
+console.log(vec2); // { x: 1, y: 2, z: 3 }
+```
+
+See [decoding variables](variables#decode-to-js-values) for more information about the decode function.
+
+## Stable pointers
+
+*New in Koffi 2.8*
+
+In some cases, the native code may need to change the output buffer at a later time, maybe during a later call or from another thread.
+
+In this case, it is **not safe to use buffers or typed arrays**! 
+
+However, you can use `koffi.alloc(type, len)` to allocate memory and get a pointer that won't move, and can be safely used at any time by the native code. Use [koffi.decode()](variables#decode-to-js-values) to read data from the pointer when needed.
+
+The example below sets up some memory to be used as an output buffer where a concatenation function appends a string on each call.
+
+```c
+#include <assert.h>
+#include <stddef.h>
+
+static char *buf_ptr;
+static size_t buf_len;
+static size_t buf_size;
+
+void reset_buffer(char *buf, size_t size)
+{
+    assert(size > 1);
+
+    buf_ptr = buf;
+    buf_len = 0;
+    buf_size = size - 1; // Keep space for trailing NUL
+
+    buf_ptr[0] = 0;
+}
+
+void append_str(const char *str)
+{
+    for (size_t i = 0; str[i] && buf_len < buf_size; i++, buf_len++) {
+        buf_ptr[buf_len] = str[i];
+    }
+    buf_ptr[buf_len] = 0;
+}
+```
+
+```js
+const reset_buffer = lib.func('void reset_buffer(char *buf, size_t size)');
+const append_str = lib.func('void append_str(const char *str)');
+
+let output = koffi.alloc('char', 64);
+reset_buffer(output, 64);
+
+append_str('Hello');
+console.log(koffi.decode(output, 'char', -1)); // Prints Hello
+
+append_str(' World!');
+console.log(koffi.decode(output, 'char', -1)); // Prints Hello World!
+```

package/node_modules/koffi/doc/packaging.md

@@ -0,0 +1,88 @@
+# Bundling
+
+## Native modules
+
+*Simplified in Koffi 2.5.9*
+
+Koffi uses native modules to work. The NPM package contains binaries for various platforms and architectures, and the appropriate module is selected at runtime.
+
+> [!IMPORTANT]
+> Please note that Koffi is meant for Node.js (or Electron) and not for browsers! It it not possible to load native libraries inside a browser!
+
+In theory, the **packagers/bundlers should be able to find all native modules** because they are explictly listed in the Javascript file (as static strings) and package them somehow.
+
+If that is not the case, you can manually arrange to copy the `node_modules/koffi/build/koffi` directory next to your bundled script.
+
+Here is an example that would work:
+
+```text
+koffi/
+    win32_x64/
+        koffi.node
+    linux_x64/
+        koffi.node
+    ...
+MyBundle.js
+```
+
+When running in Electron, Koffi will also try to find the native module in `process.resourcesPath`. For an Electron app you could do something like this
+
+```text
+locales/
+resources/
+    koffi/
+        win32_ia32/
+            koffi.node
+        win32_x64/
+            koffi.node
+        ...
+MyApp.exe
+```
+
+## Indirect loader
+
+*New in Koffi 2.6.2*
+
+Some bundlers (such as vite) don't like when require is used with native modules.
+
+In this case, you can use `require('koffi/indirect')` but you will need to make sure that the native Koffi modules are packaged properly.
+
+# Packaging examples
+
+## Electron with electron-builder
+
+Packaging with electron-builder should work as-is.
+
+Take a look at the full [working example in the repository](https://codeberg.org/Koromix/rygel/src/branch/master/src/koffi/examples/electron-builder).
+
+## Electron Forge
+
+Packaging with Electron Force should work as-is, even when using webpack as configured initially when you run:
+
+```sh
+npm init electron-app@latest my-app -- --template=webpack
+```
+
+Take a look at the full [working example in the repository](https://codeberg.org/Koromix/rygel/src/branch/master/src/koffi/examples/electron-forge).
+
+## NW.js
+
+Packagers such as nw-builder should work as-is.
+
+You can find a full [working example in the repository](https://codeberg.org/Koromix/rygel/src/branch/master/src/koffi/examples/nwjs).
+
+## Node.js and esbuild
+
+You can easily tell esbuild to copy the native files with the copy loader and things should just work. Use something like:
+
+```sh
+esbuild index.js --platform=node --bundle --loader:.node=copy --outdir=dist/
+```
+
+You can find a full [working example in the repository](https://codeberg.org/Koromix/rygel/src/branch/master/src/koffi/examples/node-esbuild).
+
+## Node.js and yao-pkg
+
+Use [yao-pkg](https://github.com/yao-pkg/pkg) to make binary packages of your Node.js-based project.
+
+You can find a full [working example in the repository](https://codeberg.org/Koromix/rygel/src/branch/master/src/koffi/examples/yao-pkg).

package/node_modules/koffi/doc/platforms.md

@@ -0,0 +1,36 @@
+# Node.js
+
+Koffi requires a recent [Node.js](https://nodejs.org/) version with [N-API](https://nodejs.org/api/n-api.html) version 8 support:
+
+- Node < 12.22.0 is not supported
+- _Node 12.x_: Node 12.22.0 or newer
+- _Node 14.x_: Node 14.17.0 or newer
+- _Node 15.x_: Node 15.12.0 or newer
+- Node 16.0.0 or later versions
+
+Use [NVM](https://github.com/nvm-sh/nvm) to install more recent Node versions on older Linux distributions.
+
+# Supported platforms
+
+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) [^1]    | ✅ Yes      | ✅ Yes        | 🟨 Probably  | ⬜️ *N/A*    | ✅ Yes      | ✅ Yes
+x86_64 (AMD64)     | ✅ Yes      | ✅ Yes        | ✅ Yes       | ✅ Yes      | ✅ Yes      | ✅ Yes
+ARM32 LE [^2]      | ⬜️ *N/A*    | ✅ Yes        | 🟨 Probably  | ⬜️ *N/A*    | 🟨 Probably | 🟨 Probably
+ARM64 (AArch64) LE | ✅ Yes      | ✅ Yes        | ✅ Yes       | ✅ Yes      | ✅ Yes      | 🟨 Probably
+RISC-V 64 [^3]     | ⬜️ *N/A*    | ✅ Yes        | 🟨 Probably  | ⬜️ *N/A*    | 🟨 Probably | 🟨 Probably
+LoongArch64        | ⬜️ *N/A*    | ✅ Yes        | 🟨 Probably  | ⬜️ *N/A*    | 🟨 Probably | 🟨 Probably
+
+<div class="legend">✅ Yes | 🟨 Probably | ⬜️ Not applicable</div>
+
+[^1]: 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.
+[^2]: 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).
+[^3]: 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.
+
+<style>
+     table td:not(:first-child) { text-align: center; }
+</style>