@lakutata/ffi 0.0.0-stage → 3.1.5

package/dist/cjs/lib/Runtime.js

@@ -0,0 +1,209 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BUILTIN_TYPES = exports.TypeNames = exports.TYPES = void 0;
+exports.checkedPointer = checkedPointer;
+exports.copyBuffer = copyBuffer;
+exports.nativeView = nativeView;
+exports.readNative = readNative;
+exports.writeNative = writeNative;
+exports.allocateNative = allocateNative;
+exports.freeNative = freeNative;
+exports.nativeErrno = nativeErrno;
+exports.nativeWindowsError = nativeWindowsError;
+exports.typeSize = typeSize;
+const koffi_1 = __importDefault(require("koffi"));
+const NativeDeclarationException_js_1 = require("../exceptions/NativeDeclarationException.js");
+const NativeMemoryException_js_1 = require("../exceptions/NativeMemoryException.js");
+const KoffiTypes_js_1 = require("./backend/KoffiTypes.js");
+const Parser_js_1 = require("./declarations/Parser.js");
+const Platform_js_1 = require("./declarations/Platform.js");
+const Resolve_js_1 = require("./library/Resolve.js");
+/**
+ * The koffi types of the process: one per C type, whatever library declares it
+ */
+exports.TYPES = new KoffiTypes_js_1.KoffiTypes(Platform_js_1.CURRENT_PLATFORM);
+/**
+ * The C types read from their names, with the declarations of a library or the built-in types only
+ */
+class TypeNames {
+    #parser;
+    #types = new Map();
+    /**
+     * The type names of a library.
+     * @param parser Its declarations.
+     */
+    constructor(parser) {
+        this.#parser = parser;
+    }
+    /**
+     * A type, from its name.
+     * @param text Its name: `int`, `struct timeval`, `const char *`.
+     */
+    type(text) {
+        let type = this.#types.get(text);
+        if (!type) {
+            type = this.#parser.typeName(text);
+            this.#types.set(text, type);
+        }
+        return type;
+    }
+    /**
+     * The koffi type of a type name.
+     * @param text Its name.
+     */
+    koffi(text) {
+        return exports.TYPES.type(this.type(text));
+    }
+}
+exports.TypeNames = TypeNames;
+/**
+ * The type names of the built-in types (of no library)
+ */
+exports.BUILTIN_TYPES = new TypeNames(new Parser_js_1.DeclarationParser(Platform_js_1.CURRENT_PLATFORM));
+let copier;
+/**
+ * memcpy of the C library, copying native memory into buffers
+ */
+function memcpy() {
+    if (!copier) {
+        const library = process.platform === 'win32' ? koffi_1.default.load('msvcrt.dll') : (0, Resolve_js_1.loadLibrary)('c').library;
+        copier = library.func('memcpy', 'void *', ['void *', 'void *', 'size_t']);
+    }
+    return copier;
+}
+/**
+ * A pointer checked: not null, a bigint or a number
+ * @param pointer
+ * @param what
+ */
+function checkedPointer(pointer, what) {
+    if (pointer === null || pointer === undefined || pointer === 0n || pointer === 0)
+        throw new NativeMemoryException_js_1.NativeMemoryException(`${what}: the pointer is null`);
+    if (typeof pointer === 'number')
+        return BigInt(pointer);
+    if (typeof pointer !== 'bigint')
+        throw new NativeMemoryException_js_1.NativeMemoryException(`${what}: a pointer (a bigint) is expected, not ${typeof pointer}`);
+    return pointer;
+}
+/**
+ * A length checked: a non-negative integer
+ * @param length
+ * @param what
+ */
+function checkedLength(length, what) {
+    if (!Number.isInteger(length) || length < 0)
+        throw new NativeMemoryException_js_1.NativeMemoryException(`${what}: the length must be a non-negative integer (${length})`);
+    return length;
+}
+/**
+ * A copy of native memory, in a buffer of its own.
+ * @param pointer The address of the memory.
+ * @param length Its length in bytes.
+ */
+function copyBuffer(pointer, length) {
+    const buffer = Buffer.allocUnsafe(checkedLength(length, 'readBuffer'));
+    if (length)
+        memcpy()(buffer, checkedPointer(pointer, 'readBuffer'), length);
+    return buffer;
+}
+/**
+ * A view of native memory, without copy: refused in Electron, which forbids them (koffi would end the process).
+ * @param pointer The address of the memory.
+ * @param length Its length in bytes.
+ */
+function nativeView(pointer, length) {
+    if (process.versions.electron)
+        throw new NativeMemoryException_js_1.NativeMemoryException('Electron does not allow views of native memory: use readBuffer, which copies it');
+    return koffi_1.default.view(checkedPointer(pointer, 'viewBuffer'), checkedLength(length, 'viewBuffer'));
+}
+/**
+ * A value read from native memory, converted as the package gives values (64-bit integers as bigints).
+ * @param names The type names to read the type with.
+ * @param pointer The address.
+ * @param type The type name.
+ * @param count The number of values, for an array.
+ */
+function readNative(names, pointer, type, count) {
+    const cType = names.type(type);
+    const address = checkedPointer(pointer, 'read');
+    const converter = exports.TYPES.converter(cType);
+    if (count === undefined) {
+        const value = koffi_1.default.decode(address, exports.TYPES.type(cType));
+        return converter?.fromNative ? converter.fromNative(value) : value;
+    }
+    const values = Array.from(koffi_1.default.decode(address, exports.TYPES.type(cType), checkedLength(count, 'readArray')));
+    return converter?.fromNative ? values.map(converter.fromNative) : values;
+}
+/**
+ * A value written to native memory.
+ * @param names The type names to read the type with.
+ * @param pointer The address.
+ * @param type The type name.
+ * @param value The value.
+ */
+function writeNative(names, pointer, type, value) {
+    const cType = names.type(type);
+    const converter = exports.TYPES.converter(cType);
+    koffi_1.default.encode(checkedPointer(pointer, 'write'), exports.TYPES.type(cType), converter?.toNative ? converter.toNative(value) : value);
+}
+/**
+ * Native memory allocated for values of a type (C's malloc: freed by freeNative).
+ * @param names The type names to read the type with.
+ * @param type The type name.
+ * @param count The number of values.
+ */
+function allocateNative(names, type, count = 1) {
+    if (!Number.isInteger(count) || count < 1)
+        throw new NativeMemoryException_js_1.NativeMemoryException(`allocMemory: the count must be a positive integer (${count})`);
+    const pointer = koffi_1.default.alloc(names.koffi(type), count);
+    return typeof pointer === 'bigint' ? pointer : koffi_1.default.address(pointer);
+}
+/**
+ * Free native memory allocated by allocateNative (or by the malloc of the C library the package is built with).
+ * @param pointer The address.
+ */
+function freeNative(pointer) {
+    koffi_1.default.free(checkedPointer(pointer, 'freeMemory'));
+}
+//The _errno() of each C library of Windows
+const windowsErrno = new Map();
+let windowsLastError;
+/**
+ * The errno of the last call made by the thread: on Windows, the one of the C library of Microsoft (ucrtbase.dll), each
+ * C library having its own; elsewhere the one koffi keeps after each call.
+ * @param crt On Windows, the C library the function called uses.
+ */
+function nativeErrno(crt = 'ucrtbase.dll') {
+    if (process.platform !== 'win32')
+        return koffi_1.default.errno();
+    const name = crt.toLowerCase();
+    let errno = windowsErrno.get(name);
+    if (!errno) {
+        errno = koffi_1.default.load(crt).func('_errno', 'int *', []);
+        windowsErrno.set(name, errno);
+    }
+    return koffi_1.default.decode(errno(), 'int');
+}
+/**
+ * The last error of the Windows API of the thread (GetLastError), kept by koffi after each call; undefined elsewhere.
+ */
+function nativeWindowsError() {
+    if (process.platform !== 'win32')
+        return undefined;
+    windowsLastError ??= koffi_1.default.load('kernel32.dll').func('__stdcall', 'GetLastError', 'uint32_t', []);
+    return windowsLastError();
+}
+/**
+ * The size of a type on the platform, by its name.
+ * @param names The type names.
+ * @param type The type name.
+ */
+function typeSize(names, type) {
+    const cType = names.type(type);
+    if (cType.kind === 'function')
+        throw new NativeDeclarationException_js_1.NativeDeclarationException(`A function has no size: ${type}`);
+    return koffi_1.default.sizeof(exports.TYPES.type(cType));
+}

package/dist/cjs/lib/backend/Functions.d.ts

@@ -0,0 +1,65 @@
+import { type LibraryHandle } from 'koffi';
+import { type FunctionDeclaration, type FunctionType } from '../declarations/Types.js';
+import { type KoffiType, type KoffiTypes } from './KoffiTypes.js';
+/**
+ * How a function is bound
+ */
+export interface BindOptions {
+    /**
+     * Whether it runs in a thread of the pool, returning a promise
+     */
+    readonly async?: boolean;
+    /**
+     * Frees the strings it gives (its result, its output strings) once read
+     */
+    readonly free?: (pointer: unknown) => void;
+    /**
+     * Its 64-bit integers (its result, its output integers) as numbers rather than bigints: a RangeError when one is not
+     * a safe integer
+     */
+    readonly int64?: 'bigint' | 'number';
+    /**
+     * The asynchronous calls of the library: counted, refused once it is closed
+     */
+    readonly calls?: CallTracker;
+}
+/**
+ * Counts the asynchronous calls of a library
+ */
+export interface CallTracker {
+    /**
+     * Before a call: throws once the library is closed
+     */
+    start(): void;
+    /**
+     * Once a call has returned
+     */
+    end(): void;
+}
+/**
+ * The koffi types of the extra arguments of a variadic function, by the C type names given before them
+ */
+export type VariadicTypes = (text: string) => KoffiType;
+/**
+ * A 64-bit integer as a number, when it is a safe one
+ * @param value
+ */
+export declare function toSafeNumber(value: unknown): unknown;
+/**
+ * A JS function given as a callback, its arguments and its result converted when its prototype has 64-bit integers or
+ * structs with bitfields; the same function otherwise
+ * @param type
+ * @param types
+ * @param callback
+ */
+export declare function convertedCallback(type: FunctionType, types: KoffiTypes, callback: (...args: any[]) => any): (...args: any[]) => any;
+/**
+ * A function of a library, bound by its declaration: the function of koffi itself when nothing has to be converted,
+ * else a function converting its arguments and its result; a function returning a promise when asynchronous
+ * @param library
+ * @param declaration
+ * @param types
+ * @param variadicTypes
+ * @param options
+ */
+export declare function bindFunction(library: LibraryHandle, declaration: FunctionDeclaration, types: KoffiTypes, variadicTypes: VariadicTypes, options?: BindOptions): (...args: any[]) => any;

package/dist/cjs/lib/backend/Functions.js

@@ -0,0 +1,214 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toSafeNumber = toSafeNumber;
+exports.convertedCallback = convertedCallback;
+exports.bindFunction = bindFunction;
+const koffi_1 = __importDefault(require("koffi"));
+const NativeDeclarationException_js_1 = require("../../exceptions/NativeDeclarationException.js");
+const Types_js_1 = require("../declarations/Types.js");
+const KoffiTypes_js_1 = require("./KoffiTypes.js");
+/**
+ * A 64-bit integer as a number, when it is a safe one
+ * @param value
+ */
+function toSafeNumber(value) {
+    if (typeof value !== 'bigint')
+        return value;
+    if (value > BigInt(Number.MAX_SAFE_INTEGER) || value < BigInt(Number.MIN_SAFE_INTEGER))
+        throw new RangeError(`${value} is not a safe integer: declare the function without int64: 'number' to get a bigint`);
+    return Number(value);
+}
+/**
+ * Whether a type is a pointer to a string type (char *, char16_t *, wchar_t *)
+ * @param type
+ */
+function isString(type) {
+    return type.kind === 'pointer' && type.to.kind === 'primitive' && ['char', 'char16', 'wchar'].includes(type.to.name);
+}
+/**
+ * The koffi type of a string type, freed by a function once read
+ * @param type
+ * @param free
+ */
+function disposableString(type, free) {
+    const name = type.to.name;
+    return koffi_1.default.disposable(name === 'char' ? 'char *' : name === 'char16' ? 'char16_t *' : 'wchar_t *', free);
+}
+/**
+ * A JS function given as a callback, its arguments and its result converted when its prototype has 64-bit integers or
+ * structs with bitfields; the same function otherwise
+ * @param type
+ * @param types
+ * @param callback
+ */
+function convertedCallback(type, types, callback) {
+    const steps = type.parameters.map((parameter) => types.converter(parameter.type));
+    const result = types.converter(type.result);
+    if (!steps.some((step) => !!step?.fromNative) && !result?.toNative)
+        return callback;
+    return (...args) => {
+        for (let i = 0; i < steps.length; i++)
+            if (steps[i]?.fromNative)
+                args[i] = steps[i].fromNative(args[i]);
+        const value = callback(...args);
+        return result?.toNative ? result.toNative(value) : value;
+    };
+}
+/**
+ * The steps of the arguments of a function: the callbacks converted, the structs with bitfields written, the output
+ * integers and structs read back as the package gives them
+ * @param type
+ * @param types
+ * @param options
+ */
+function argumentSteps(type, types, options) {
+    const steps = [];
+    type.parameters.forEach((parameter, index) => {
+        const target = parameter.type.kind === 'pointer' ? parameter.type.to : undefined;
+        if (parameter.direction === 'in') {
+            if (target?.kind === 'function') {
+                const prototype = target;
+                const probe = () => undefined;
+                if (convertedCallback(prototype, types, probe) === probe)
+                    return;
+                steps.push({ index: index, before: (value) => typeof value === 'function' ? convertedCallback(prototype, types, value) : value });
+                return;
+            }
+            const converter = types.converter(target && (target.kind === 'struct' || target.kind === 'union') ? target : parameter.type);
+            if (converter?.toNative && (parameter.type.kind !== 'pointer' || target?.kind === 'struct' || target?.kind === 'union')) {
+                steps.push({ index: index, before: (value) => isPlainObject(value) ? converter.toNative(value) : value });
+            }
+            return;
+        }
+        if (!target)
+            return;
+        //An output integer: the array given gets a bigint (or a number, with int64: 'number')
+        if ((target.kind === 'primitive' && (0, Types_js_1.primitiveBig)(target.name)) || (target.kind === 'enum' && (0, Types_js_1.primitiveBig)(target.base))) {
+            const convert = options.int64 === 'number' ? toSafeNumber : KoffiTypes_js_1.toBigInt;
+            steps.push({ index: index, after: (given) => {
+                    if (Array.isArray(given))
+                        given[0] = convert(given[0]);
+                } });
+            return;
+        }
+        //An output struct: filled through an object koffi knows, then given back as the package gives it
+        const converter = types.converter(target);
+        if (converter && (target.kind === 'struct' || target.kind === 'union')) {
+            steps.push({
+                index: index,
+                before: (value) => isPlainObject(value) ? (parameter.direction === 'inout' && converter.toNative ? converter.toNative(value) : { ...value }) : value,
+                after: (given, passed) => {
+                    if (isPlainObject(given) && passed !== given)
+                        Object.assign(given, converter.fromNative ? converter.fromNative(passed) : passed);
+                }
+            });
+        }
+    });
+    return steps;
+}
+/**
+ * Whether a value is a plain object (a struct given as an object), not a pointer, a buffer or a koffi union
+ * @param value
+ */
+function isPlainObject(value) {
+    return !!value && typeof value === 'object' && !ArrayBuffer.isView(value) && !Array.isArray(value) && Object.getPrototypeOf(value) === Object.prototype;
+}
+/**
+ * A function of a library, bound by its declaration: the function of koffi itself when nothing has to be converted,
+ * else a function converting its arguments and its result; a function returning a promise when asynchronous
+ * @param library
+ * @param declaration
+ * @param types
+ * @param variadicTypes
+ * @param options
+ */
+function bindFunction(library, declaration, types, variadicTypes, options = {}) {
+    const type = declaration.type;
+    if (options.async && type.variadic)
+        throw new NativeDeclarationException_js_1.NativeDeclarationException(`The variadic function ${declaration.name} cannot be called asynchronously`);
+    const result = options.free && isString(type.result) ? disposableString(type.result, options.free) : types.type(type.result);
+    const parameters = type.parameters.map((parameter) => {
+        const target = parameter.type.kind === 'pointer' ? parameter.type.to : undefined;
+        if (parameter.direction === 'in')
+            return types.type(parameter.type);
+        if (!target)
+            throw new NativeDeclarationException_js_1.NativeDeclarationException(`The parameter ${parameter.name ?? ''} of ${declaration.name} is ${parameter.direction === 'out' ? '_Out_' : '_Inout_'} but not a pointer (${(0, Types_js_1.typeText)(parameter.type)})`.replace('  ', ' '));
+        const pointed = options.free && isString(target) ? koffi_1.default.pointer(disposableString(target, options.free)) : types.type(parameter.type);
+        return parameter.direction === 'out' ? koffi_1.default.out(pointed) : koffi_1.default.inout(pointed);
+    });
+    let bound;
+    try {
+        bound = library.func(`__${type.convention}`, declaration.symbol, result, type.variadic ? [...parameters, '...'] : parameters);
+    }
+    catch (error) {
+        throw new NativeDeclarationException_js_1.NativeDeclarationException(`The function ${declaration.name} cannot be bound (${declaration.symbol}): ${error.message}`);
+    }
+    const steps = argumentSteps(type, types, options);
+    const resultConverter = options.int64 === 'number' && (type.result.kind === 'primitive' && (0, Types_js_1.primitiveBig)(type.result.name)) ? toSafeNumber : types.converter(type.result)?.fromNative;
+    const fixed = type.parameters.length;
+    const prepare = (args) => {
+        const passed = args.slice();
+        for (const step of steps)
+            if (step.before)
+                passed[step.index] = step.before(args[step.index]);
+        //The extra arguments of a variadic function: the koffi type of each C type name given
+        if (type.variadic)
+            for (let i = fixed; i < passed.length; i += 2)
+                if (typeof passed[i] === 'string')
+                    passed[i] = variadicTypes(passed[i]);
+        return passed;
+    };
+    const finish = (args, passed, value) => {
+        for (const step of steps)
+            if (step.after)
+                step.after(args[step.index], passed[step.index]);
+        return resultConverter ? resultConverter(value) : value;
+    };
+    if (!options.async) {
+        if (!steps.length && !resultConverter && !type.variadic)
+            return bound;
+        return (...args) => {
+            const passed = prepare(args);
+            return finish(args, passed, bound(...passed));
+        };
+    }
+    return (...args) => {
+        //Refused once the library is closed: a rejected promise, as every failure of the call
+        try {
+            options.calls?.start();
+        }
+        catch (error) {
+            return Promise.reject(error);
+        }
+        let passed;
+        try {
+            passed = prepare(args);
+        }
+        catch (error) {
+            options.calls?.end();
+            return Promise.reject(error);
+        }
+        return new Promise((resolve, reject) => {
+            try {
+                bound.async(...passed, (error, value) => {
+                    options.calls?.end();
+                    if (error)
+                        return reject(error);
+                    try {
+                        resolve(finish(args, passed, value));
+                    }
+                    catch (conversion) {
+                        reject(conversion);
+                    }
+                });
+            }
+            catch (error) {
+                options.calls?.end();
+                reject(error);
+            }
+        });
+    };
+}

package/dist/cjs/lib/backend/KoffiTypes.d.ts

@@ -0,0 +1,53 @@
+import koffi, { type TypeObject } from 'koffi';
+import type { Platform } from '../declarations/Platform.js';
+import { type CType, type FunctionType } from '../declarations/Types.js';
+/**
+ * A type as koffi takes it: its name, its object, or its object with a direction (an output parameter)
+ */
+export type KoffiType = string | TypeObject | ReturnType<typeof koffi.out>;
+/**
+ * How a value goes between the user and koffi, when koffi does not give or take it as the package does: the 64-bit
+ * integers always bigints, the bitfields of a struct read and written by their names
+ */
+export interface Converter {
+    /**
+     * A value of the user to the value koffi takes
+     */
+    readonly toNative?: (value: any) => any;
+    /**
+     * A value koffi gives to the value of the user
+     */
+    readonly fromNative?: (value: any) => any;
+}
+/**
+ * A value of a 64-bit integer type, as a bigint
+ * @param value
+ */
+export declare function toBigInt(value: unknown): unknown;
+/**
+ * The koffi types of the C types of the declarations, made once each (koffi never frees a type): anonymous, so the
+ * types of two libraries never meet; the structs koffi cannot lay out (bitfields, packing) laid out by the package
+ */
+export declare class KoffiTypes {
+    #private;
+    /**
+     * The koffi types of a platform.
+     * @param platform The platform of the process.
+     */
+    constructor(platform: Platform);
+    /**
+     * The koffi type of a C type, as a value: a member, a result, a parameter without direction.
+     * @param type The C type.
+     */
+    type(type: CType): KoffiType;
+    /**
+     * The koffi prototype of a function type: the type of its callbacks.
+     * @param type The function type.
+     */
+    prototype(type: FunctionType): TypeObject;
+    /**
+     * The converter of a C type, null when koffi gives and takes its values as the package does.
+     * @param type The C type.
+     */
+    converter(type: CType): Converter | null;
+}