@sng2c/pi-the-giver 0.1.0 → 0.1.1

package/node_modules/koffi/doc/variables.md

@@ -0,0 +1,102 @@
+# Variable definitions
+
+*New in Koffi 2.6*
+
+To find an exported and  declare a variable, use `lib.symbol(name, type)`. You need to specify its name and its type.
+
+```c
+int my_int = 42;
+const char *my_string = NULL;
+```
+
+```js
+const my_int = lib.symbol('my_int', 'int');
+const my_string = lib.symbol('my_string', 'const char *');
+```
+
+You cannot directly manipulate these variables, use:
+
+- [koffi.decode()](#decode-to-js-values) to read their value
+- [koffi.encode()](#encode-to-c-memory) to change their valuèe
+
+# Decode to JS values
+
+*New in Koffi 2.2, changed in Koffi 2.3*
+
+Use `koffi.decode()` to decode C pointers, wrapped as external objects or as simple numbers.
+
+Some arguments are optional and this function can be called in several ways:
+
+- `koffi.decode(value, type)`: no offset
+- `koffi.decode(value, offset, type)`: explicit offset to add to the pointer before decoding
+
+By default, Koffi expects NUL terminated strings when decoding them. See below if you need to specify the string length.
+
+The following example illustrates how to decode an integer and a C string variable.
+
+```c
+int my_int = 42;
+const char *my_string = "foobar";
+```
+
+```js
+const my_int = lib.symbol('my_int', 'int');
+const my_string = lib.symbol('my_string', 'const char *');
+
+console.log(koffi.decode(my_int, 'int')) // Prints 42
+console.log(koffi.decode(my_string, 'const char *')) // Prints "foobar"
+```
+
+There is also an optional ending `length` argument that you can use in two cases:
+
+- Use it to give the number of bytes to decode in non-NUL terminated strings: `koffi.decode(value, 'char *', 5)`
+- Decode consecutive values into an array. For example, here is how you can decode an array with 3 float values: `koffi.decode(value, 'float', 3)`. This is equivalent to `koffi.decode(value, koffi.array('float', 3))`.
+
+The example below will decode the symbol `my_string` defined above but only the first three bytes.
+
+```js
+// Only decode 3 bytes from the C string my_string
+console.log(koffi.decode(my_string, 'const char *', 3)) // Prints "foo"
+```
+
+> [!NOTE]
+> In Koffi 2.2 and earlier versions, the length argument is only used to decode strings and is ignored otherwise.
+
+# Encode to C memory
+
+*New in Koffi 2.6*
+
+Use `koffi.encode()` to encode JS values into C symbols or pointers, wrapped as external objects or as simple numbers.
+
+Some arguments are optional and this function can be called in several ways:
+
+- `koffi.encode(ref, type, value)`: no offset
+- `koffi.encode(ref, offset, type, value)`: explicit offset to add to the pointer before encoding
+
+We'll reuse the examples shown above and change the variable values with `koffi.encode()`.
+
+```c
+int my_int = 42;
+const char *my_string = NULL;
+```
+
+```js
+const my_int = lib.symbol('my_int', 'int');
+const my_string = lib.symbol('my_string', 'const char *');
+
+console.log(koffi.decode(my_int, 'int')) // Prints 42
+console.log(koffi.decode(my_string, 'const char *')) // Prints null
+
+koffi.encode(my_int, 'int', -1);
+koffi.encode(my_string, 'const char *', 'Hello World!');
+
+console.log(koffi.decode(my_int, 'int')) // Prints -1
+console.log(koffi.decode(my_string, 'const char *')) // Prints "Hello World!"
+```
+
+When encoding strings (either directly or embedded in arrays or structs), the memory will be bound to the raw pointer value and managed by Koffi. You can assign to the same string again and again without any leak or risk of use-after-free.
+
+There is also an optional ending `length` argument that you can use to encode an array. For example, here is how you can encode an array with 3 float values: `koffi.encode(symbol, 'float', [1, 2, 3], 3)`. This is equivalent to `koffi.encode(symbol, koffi.array('float', 3), [1, 2, 3])`.
+
+> [!NOTE]
+> The length argument did not work correctly before Koffi 2.6.11.

package/node_modules/koffi/index.d.ts

@@ -0,0 +1,288 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2025 Niels Martignène <niels.martignene@protonmail.com>
+
+type LoadOptions = {
+    lazy?: boolean,
+    global?: boolean,
+    deep?: boolean
+};
+
+export function load(path: string | null, options?: LoadOptions): IKoffiLib;
+
+interface IKoffiCType { __brand: 'IKoffiCType' }
+interface IKoffiPointerCast { __brand: 'IKoffiPointerCast' }
+interface IKoffiRegisteredCallback { __brand: 'IKoffiRegisteredCallback' }
+
+type PrimitiveKind = 'Void' | 'Bool' | 'Int8' | 'UInt8' | 'Int16' | 'Int16S' | 'UInt16' | 'UInt16S' |
+                     'Int32' | 'Int32S' | 'UInt32' | 'UInt32S' | 'Int64' | 'Int64S' | 'UInt64' | 'UInt64S' |
+                     'String' | 'String16' | 'Pointer' | 'Record' | 'Union' | 'Array' | 'Float32' | 'Float64' |
+                     'Prototype' | 'Callback';
+type ArrayHint = 'Array' | 'Typed' | 'String';
+
+type TypeSpec = string | IKoffiCType;
+type TypeSpecWithAlignment = TypeSpec | [number, TypeSpec];
+type TypeInfo = {
+    name: string;
+    primitive: PrimitiveKind;
+    size: number;
+    alignment: number;
+    disposable: boolean;
+    length?: number;
+    hint?: ArrayHint;
+    ref?: IKoffiCType;
+    members?: Record<string, { name: string, type: IKoffiCType, offset: number }>;
+};
+type KoffiFunction = {
+    (...args: any[]) : any;
+    async: (...args: any[]) => any;
+    info: {
+        name: string,
+        arguments: IKoffiCType[],
+        result: IKoffiCType
+    };
+};
+
+export type KoffiFunc<T extends (...args: any) => any> = T & {
+   async: (...args: [...Parameters<T>, (err: any, result: ReturnType<T>) => void]) => void;
+   info: {
+      name: string;
+      arguments: IKoffiCType[];
+      result: IKoffiCType;
+   };
+};
+
+export interface IKoffiLib {
+    func(definition: string): KoffiFunction;
+    func(name: string | number, result: TypeSpec, arguments: TypeSpec[]): KoffiFunction;
+    func(convention: string, name: string | number, result: TypeSpec, arguments: TypeSpec[]): KoffiFunction;
+
+    /** @deprecated */ cdecl(definition: string): KoffiFunction;
+    /** @deprecated */ cdecl(name: string | number, result: TypeSpec, arguments: TypeSpec[]): KoffiFunction;
+    /** @deprecated */ stdcall(definition: string): KoffiFunction;
+    /** @deprecated */ stdcall(name: string | number, result: TypeSpec, arguments: TypeSpec[]): KoffiFunction;
+    /** @deprecated */ fastcall(definition: string): KoffiFunction;
+    /** @deprecated */ fastcall(name: string | number, result: TypeSpec, arguments: TypeSpec[]): KoffiFunction;
+    /** @deprecated */ thiscall(definition: string): KoffiFunction;
+    /** @deprecated */ thiscall(name: string | number, result: TypeSpec, arguments: TypeSpec[]): KoffiFunction;
+
+    symbol(name: string, type: TypeSpec): any;
+
+    unload(): void;
+}
+
+export function struct(name: string | null | undefined, def: Record<string, TypeSpecWithAlignment>): IKoffiCType;
+export function struct(ref: IKoffiCType, def: Record<string, TypeSpecWithAlignment>): IKoffiCType;
+export function struct(def: Record<string, TypeSpecWithAlignment>): IKoffiCType;
+export function pack(name: string | null | undefined, def: Record<string, TypeSpecWithAlignment>): IKoffiCType;
+export function pack(ref: IKoffiCType, def: Record<string, TypeSpecWithAlignment>): IKoffiCType;
+export function pack(def: Record<string, TypeSpecWithAlignment>): IKoffiCType;
+
+export function union(name: string | null | undefined, def: Record<string, TypeSpecWithAlignment>): IKoffiCType;
+export function union(ref: IKoffiCType, def: Record<string, TypeSpecWithAlignment>): IKoffiCType;
+export function union(def: Record<string, TypeSpecWithAlignment>): IKoffiCType;
+
+export class Union {
+    constructor(type: TypeSpec);
+    [s: string]: any;
+}
+
+export function array(ref: TypeSpec, len: number, hint?: ArrayHint | null): IKoffiCType;
+export function array(ref: TypeSpec, countedBy: string, maxLen: number, hint?: ArrayHint | null): IKoffiCType;
+
+export function opaque(name: string | null | undefined): IKoffiCType;
+export function opaque(): IKoffiCType;
+/** @deprecated */ export function handle(name: string | null | undefined): IKoffiCType;
+/** @deprecated */ export function handle(): IKoffiCType;
+
+export function pointer(ref: TypeSpec): IKoffiCType;
+export function pointer(ref: TypeSpec, count: number): IKoffiCType;
+export function pointer(name: string | null | undefined, ref: TypeSpec, countedBy?: string | null): IKoffiCType;
+export function pointer(name: string | null | undefined, ref: TypeSpec, count: number): IKoffiCType;
+
+export function out(type: TypeSpec): IKoffiCType;
+export function inout(type: TypeSpec): IKoffiCType;
+
+export function disposable(type: TypeSpec): IKoffiCType;
+export function disposable(type: TypeSpec, freeFunction: Function): IKoffiCType;
+export function disposable(name: string | null | undefined, type: TypeSpec): IKoffiCType;
+export function disposable(name: string | null | undefined, type: TypeSpec, freeFunction: Function): IKoffiCType;
+
+export function proto(definition: string): IKoffiCType;
+export function proto(result: TypeSpec, arguments: TypeSpec[]): IKoffiCType;
+export function proto(convention: string, result: TypeSpec, arguments: TypeSpec[]): IKoffiCType;
+export function proto(name: string | null | undefined, result: TypeSpec, arguments: TypeSpec[]): IKoffiCType;
+export function proto(convention: string, name: string | null | undefined, result: TypeSpec, arguments: TypeSpec[]): IKoffiCType;
+/** @deprecated */ export function callback(definition: string): IKoffiCType;
+/** @deprecated */ export function callback(result: TypeSpec, arguments: TypeSpec[]): IKoffiCType;
+/** @deprecated */ export function callback(convention: string, result: TypeSpec, arguments: TypeSpec[]): IKoffiCType;
+/** @deprecated */ export function callback(name: string | null | undefined, result: TypeSpec, arguments: TypeSpec[]): IKoffiCType;
+/** @deprecated */ export function callback(convention: string, name: string | null | undefined, result: TypeSpec, arguments: TypeSpec[]): IKoffiCType;
+
+export function register(callback: Function, type: TypeSpec): IKoffiRegisteredCallback;
+export function register(thisValue: any, callback: Function, type: TypeSpec): IKoffiRegisteredCallback;
+export function unregister(callback: IKoffiRegisteredCallback): void;
+
+export function as(value: any, type: TypeSpec): IKoffiPointerCast;
+export function decode(value: any, type: TypeSpec): any;
+export function decode(value: any, type: TypeSpec, len: number): any;
+export function decode(value: any, offset: number, type: TypeSpec): any;
+export function decode(value: any, offset: number, type: TypeSpec, len: number): any;
+export function address(value: any): bigint;
+export function call(value: any, type: TypeSpec, ...args: any[]): any;
+export function encode(ref: any, type: TypeSpec, value: any): void;
+export function encode(ref: any, type: TypeSpec, value: any, len: number): void;
+export function encode(ref: any, offset: number, type: TypeSpec): void;
+export function encode(ref: any, offset: number, type: TypeSpec, value: any): void;
+export function encode(ref: any, offset: number, type: TypeSpec, value: any, len: number): void;
+export function view(ref: any, len: number): ArrayBuffer;
+
+export function sizeof(type: TypeSpec): number;
+export function alignof(type: TypeSpec): number;
+export function offsetof(type: TypeSpec, member_name: string): number;
+export function resolve(type: TypeSpec): IKoffiCType;
+export function introspect(type: TypeSpec): TypeInfo;
+
+export function alias(name: string, type: TypeSpec): IKoffiCType;
+
+type KoffiConfig = {
+    sync_stack_size?: number
+    sync_heap_size?: number
+    async_stack_size?: number
+    async_heap_size?: number
+    resident_async_pools?: number
+    max_async_calls?: number
+    max_type_size?: number
+};
+type KoffiStats = {
+    disposed: number
+};
+
+export function config(): KoffiConfig;
+export function config(cfg: KoffiConfig): KoffiConfig;
+export function stats(): KoffiStats;
+
+export function alloc(type: TypeSpec, length: number): any;
+export function free(value: any): void;
+
+export function errno(): number;
+export function errno(value: number): number;
+
+export function reset(): void;
+
+export const internal: Boolean;
+export const extension: String;
+
+export const os: {
+    errno: Record<string, number>
+};
+
+// https://koffi.dev/input#standard-types
+type PrimitiveTypes =
+    | 'bool'
+    | 'char'
+    | 'char16_t'
+    | 'char16'
+    | 'char32_t'
+    | 'char32'
+    | 'double'
+    | 'float'
+    | 'float32'
+    | 'float64'
+    | 'int'
+    | 'int8_t'
+    | 'int8'
+    | 'int16_be_t'
+    | 'int16_be'
+    | 'int16_le_t'
+    | 'int16_le'
+    | 'int16_t'
+    | 'int16'
+    | 'int32_be_t'
+    | 'int32_be'
+    | 'int32_le_t'
+    | 'int32_le'
+    | 'int32_t'
+    | 'int32'
+    | 'int64_be_t'
+    | 'int64_be'
+    | 'int64_le_t'
+    | 'int64_le'
+    | 'int64_t'
+    | 'int64'
+    | 'intptr_t'
+    | 'intptr'
+    | 'long long'
+    | 'long'
+    | 'longlong'
+    | 'short'
+    | 'size_t'
+    | 'str'
+    | 'str16'
+    | 'str32'
+    | 'string'
+    | 'string16'
+    | 'string32'
+    | 'uchar'
+    | 'uint'
+    | 'uint8_t'
+    | 'uint8'
+    | 'uint16_be_t'
+    | 'uint16_be'
+    | 'uint16_le_t'
+    | 'uint16_le'
+    | 'uint16_t'
+    | 'uint16'
+    | 'uint32_be_t'
+    | 'uint32_be'
+    | 'uint32_le_t'
+    | 'uint32_le'
+    | 'uint32_t'
+    | 'uint32'
+    | 'uint64_be_t'
+    | 'uint64_be'
+    | 'uint64_le_t'
+    | 'uint64_le'
+    | 'uint64_t'
+    | 'uint64'
+    | 'uintptr_t'
+    | 'uintptr'
+    | 'ulong'
+    | 'ulonglong'
+    | 'unsigned char'
+    | 'unsigned int'
+    | 'unsigned long long'
+    | 'unsigned long'
+    | 'unsigned short'
+    | 'ushort'
+    | 'void'
+    | 'wchar'
+    | 'wchar_t';
+export const types: Record<PrimitiveTypes, IKoffiCType>;
+
+export interface IKoffiPollOptions {
+    readable?: boolean;
+    writable?: boolean;
+    disconnect?: boolean;
+}
+
+export interface IKoffiPollEvents {
+    readable: boolean;
+    writable: boolean;
+    disconnect: boolean;
+}
+
+export namespace node {
+    export const env: { __brand: 'IKoffiNodeEnv' };
+
+    export class PollHandle {
+        start(opts: IKoffiPollOptions, callback: (ev: IKoffiPollEvents) => void): void;
+        start(callback: (ev: IKoffiPollEvents) => void): void;
+        stop(): void;
+        close(): void;
+        unref(): void;
+        ref(): void;
+    }
+
+    export function poll(fd: number, opts: IKoffiPollOptions, callback: (ev: IKoffiPollEvents) => void): PollHandle;
+    export function poll(fd: number, callback: (ev: IKoffiPollEvents) => void): PollHandle;
+}