@lakutata/ffi 0.0.0-stage → 3.1.5

package/dist/esm/lib/Memory.js

@@ -0,0 +1,210 @@
+import koffi from 'koffi';
+import { BUILTIN_TYPES, checkedPointer, copyBuffer, allocateNative, freeNative, nativeErrno, nativeView, nativeWindowsError, readNative, typeSize, writeNative } from './Runtime.js';
+/**
+ * Read a C string (UTF-8, ended by a NUL byte) from native memory: a `char *` given as a pointer (a `void *` result, an
+ * argument of a callback, a member of a struct).
+ * @param pointer Its address.
+ * @param length Its length in bytes, when it is not ended by a NUL byte.
+ * @returns The string.
+ * @example
+ * ```typescript
+ * import {readCString, type Pointer} from '@lakutata/ffi'
+ *
+ * export function messageOf(pointer: Pointer): string {
+ *     return readCString(pointer)
+ * }
+ * ```
+ */
+export function readCString(pointer, length) {
+    const address = checkedPointer(pointer, 'readCString');
+    return length === undefined ? koffi.decode.string(address) : koffi.decode.string(address, length);
+}
+/**
+ * Read a wide string from native memory: a `wchar_t *` (UTF-16 on Windows, UTF-32 elsewhere), ended by a NUL character.
+ * @param pointer Its address.
+ * @param length Its length in characters, when it is not ended by a NUL character.
+ * @returns The string.
+ * @example
+ * ```typescript
+ * import {readWString, type Pointer} from '@lakutata/ffi'
+ *
+ * export function titleOf(pointer: Pointer): string {
+ *     return readWString(pointer)
+ * }
+ * ```
+ */
+export function readWString(pointer, length) {
+    const address = checkedPointer(pointer, 'readWString');
+    return length === undefined ? koffi.decode.wstring(address) : koffi.decode.wstring(address, length);
+}
+/**
+ * Copy native memory into a buffer of its own, which stays valid once the native memory is freed (about 10 GB/s).
+ * @param pointer The address of the memory.
+ * @param length Its length in bytes.
+ * @returns The copy.
+ * @example
+ * ```typescript
+ * import {readBuffer, type Pointer} from '@lakutata/ffi'
+ *
+ * export function frameOf(pixels: Pointer, width: number, height: number): Buffer {
+ *     return readBuffer(pixels, width * height * 4)
+ * }
+ * ```
+ */
+export function readBuffer(pointer, length) {
+    return copyBuffer(pointer, length);
+}
+/**
+ * A view of native memory, without copy: worth it for large blocks read often (8 MiB: about 0.13 ms rather than 1 ms
+ * for a copy). The view must not be used once the native memory is freed: the process would crash. Electron forbids
+ * these views: it throws there (use readBuffer).
+ * @param pointer The address of the memory.
+ * @param length Its length in bytes.
+ * @returns The memory, as an ArrayBuffer.
+ * @throws {NativeMemoryException} In Electron, or for a null pointer.
+ * @example
+ * ```typescript
+ * import {viewBuffer, type Pointer} from '@lakutata/ffi'
+ *
+ * export function firstPixel(pixels: Pointer): number {
+ *     return new Uint32Array(viewBuffer(pixels, 4))[0]
+ * }
+ * ```
+ */
+export function viewBuffer(pointer, length) {
+    return nativeView(pointer, length);
+}
+/**
+ * Read a value of a built-in type from native memory (`int`, `double`, `uint64_t`, `char *`…): the 64-bit integers as
+ * bigints. The types of a library are read by `read()` of the library.
+ * @param pointer Its address.
+ * @param type Its type.
+ * @returns The value.
+ * @example
+ * ```typescript
+ * import {readValue, type Pointer} from '@lakutata/ffi'
+ *
+ * export function countAt(pointer: Pointer): number {
+ *     return readValue(pointer, 'int32_t') as number
+ * }
+ * ```
+ */
+export function readValue(pointer, type) {
+    return readNative(BUILTIN_TYPES, pointer, type);
+}
+/**
+ * Read an array of values of a built-in type from native memory.
+ * @param pointer The address of its first element.
+ * @param type The type of its elements (`char *` reads strings).
+ * @param count Its length.
+ * @returns The values.
+ * @example
+ * ```typescript
+ * import {readArray, type Pointer} from '@lakutata/ffi'
+ *
+ * //The row of a callback of sqlite3_exec: char **values
+ * export function rowOf(values: Pointer, count: number): string[] {
+ *     return readArray(values, 'char *', count) as string[]
+ * }
+ * ```
+ */
+export function readArray(pointer, type, count) {
+    return readNative(BUILTIN_TYPES, pointer, type, count);
+}
+/**
+ * Write a value of a built-in type to native memory.
+ * @param pointer Its address.
+ * @param type Its type.
+ * @param value The value.
+ * @example
+ * ```typescript
+ * import {allocMemory, freeMemory, readValue, writeValue} from '@lakutata/ffi'
+ *
+ * const counter: bigint = allocMemory('int64_t')
+ * writeValue(counter, 'int64_t', 42n)
+ * console.log(readValue(counter, 'int64_t'))
+ * freeMemory(counter)
+ * ```
+ */
+export function writeValue(pointer, type, value) {
+    writeNative(BUILTIN_TYPES, pointer, type, value);
+}
+/**
+ * Allocate native memory for values of a built-in type: memory that does not move, which a library can keep (a buffer
+ * given to a function is valid during the call only). Freed by freeMemory.
+ * @param type The type of the values.
+ * @param count Their number.
+ * @returns Its address.
+ * @example
+ * ```typescript
+ * import {allocMemory, freeMemory} from '@lakutata/ffi'
+ *
+ * const buffer: bigint = allocMemory('uint8_t', 4096)
+ * freeMemory(buffer)
+ * ```
+ */
+export function allocMemory(type, count = 1) {
+    return allocateNative(BUILTIN_TYPES, type, count);
+}
+/**
+ * Free native memory allocated by allocMemory.
+ * @param pointer Its address.
+ * @example
+ * ```typescript
+ * import {allocMemory, freeMemory} from '@lakutata/ffi'
+ *
+ * freeMemory(allocMemory('double', 16))
+ * ```
+ */
+export function freeMemory(pointer) {
+    freeNative(pointer);
+}
+/**
+ * The size of a built-in type on the platform, in bytes (`long` is 8 on 64-bit Linux and macOS, 4 on Windows).
+ * @param type The type.
+ * @returns Its size.
+ * @example
+ * ```typescript
+ * import {sizeOf} from '@lakutata/ffi'
+ *
+ * console.log(sizeOf('long'), sizeOf('wchar_t'), sizeOf('void *'))
+ * ```
+ */
+export function sizeOf(type) {
+    return typeSize(BUILTIN_TYPES, type);
+}
+/**
+ * The errno of the last native call of the thread. On Windows, each C library has its own errno: the one of the C
+ * library of Microsoft (ucrtbase.dll) by default.
+ * @param crt On Windows, the C library the function called uses (`msvcrt.dll` for the old libraries).
+ * @returns The errno.
+ * @example
+ * ```typescript
+ * import {lastErrno, loadNativeLibrary} from '@lakutata/ffi'
+ *
+ * const libc = loadNativeLibrary('c')
+ * const open = libc.func<(path: string, flags: number) => number>('int open(const char *path, int flags, ...)')
+ * if (open('/surely/missing', 0) < 0) console.log('errno', lastErrno())
+ * ```
+ */
+export function lastErrno(crt) {
+    return nativeErrno(crt);
+}
+/**
+ * The last error of the Windows API of the thread (GetLastError), kept after each native call; undefined on the other
+ * systems.
+ * @returns The error.
+ * @example
+ * ```typescript
+ * import {lastWindowsError, loadNativeLibrary} from '@lakutata/ffi'
+ *
+ * if (process.platform === 'win32') {
+ *     const kernel32 = loadNativeLibrary('kernel32.dll')
+ *     const attributes = kernel32.func<(path: string) => number>('DWORD WINAPI GetFileAttributesW(LPCWSTR path)')
+ *     if (attributes('C:\\missing') === 0xFFFFFFFF) console.log('error', lastWindowsError())
+ * }
+ * ```
+ */
+export function lastWindowsError() {
+    return nativeWindowsError();
+}

package/dist/esm/lib/Runtime.js

@@ -0,0 +1,192 @@
+import koffi from 'koffi';
+import { NativeDeclarationException } from '../exceptions/NativeDeclarationException.js';
+import { NativeMemoryException } from '../exceptions/NativeMemoryException.js';
+import { KoffiTypes } from './backend/KoffiTypes.js';
+import { DeclarationParser } from './declarations/Parser.js';
+import { CURRENT_PLATFORM } from './declarations/Platform.js';
+import { loadLibrary } from './library/Resolve.js';
+/**
+ * The koffi types of the process: one per C type, whatever library declares it
+ */
+export const TYPES = new KoffiTypes(CURRENT_PLATFORM);
+/**
+ * The C types read from their names, with the declarations of a library or the built-in types only
+ */
+export 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 TYPES.type(this.type(text));
+    }
+}
+/**
+ * The type names of the built-in types (of no library)
+ */
+export const BUILTIN_TYPES = new TypeNames(new DeclarationParser(CURRENT_PLATFORM));
+let copier;
+/**
+ * memcpy of the C library, copying native memory into buffers
+ */
+function memcpy() {
+    if (!copier) {
+        const library = process.platform === 'win32' ? koffi.load('msvcrt.dll') : 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
+ */
+export function checkedPointer(pointer, what) {
+    if (pointer === null || pointer === undefined || pointer === 0n || pointer === 0)
+        throw new NativeMemoryException(`${what}: the pointer is null`);
+    if (typeof pointer === 'number')
+        return BigInt(pointer);
+    if (typeof pointer !== 'bigint')
+        throw new 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(`${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.
+ */
+export 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.
+ */
+export function nativeView(pointer, length) {
+    if (process.versions.electron)
+        throw new NativeMemoryException('Electron does not allow views of native memory: use readBuffer, which copies it');
+    return koffi.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.
+ */
+export function readNative(names, pointer, type, count) {
+    const cType = names.type(type);
+    const address = checkedPointer(pointer, 'read');
+    const converter = TYPES.converter(cType);
+    if (count === undefined) {
+        const value = koffi.decode(address, TYPES.type(cType));
+        return converter?.fromNative ? converter.fromNative(value) : value;
+    }
+    const values = Array.from(koffi.decode(address, 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.
+ */
+export function writeNative(names, pointer, type, value) {
+    const cType = names.type(type);
+    const converter = TYPES.converter(cType);
+    koffi.encode(checkedPointer(pointer, 'write'), 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.
+ */
+export function allocateNative(names, type, count = 1) {
+    if (!Number.isInteger(count) || count < 1)
+        throw new NativeMemoryException(`allocMemory: the count must be a positive integer (${count})`);
+    const pointer = koffi.alloc(names.koffi(type), count);
+    return typeof pointer === 'bigint' ? pointer : koffi.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.
+ */
+export function freeNative(pointer) {
+    koffi.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.
+ */
+export function nativeErrno(crt = 'ucrtbase.dll') {
+    if (process.platform !== 'win32')
+        return koffi.errno();
+    const name = crt.toLowerCase();
+    let errno = windowsErrno.get(name);
+    if (!errno) {
+        errno = koffi.load(crt).func('_errno', 'int *', []);
+        windowsErrno.set(name, errno);
+    }
+    return koffi.decode(errno(), 'int');
+}
+/**
+ * The last error of the Windows API of the thread (GetLastError), kept by koffi after each call; undefined elsewhere.
+ */
+export function nativeWindowsError() {
+    if (process.platform !== 'win32')
+        return undefined;
+    windowsLastError ??= koffi.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.
+ */
+export function typeSize(names, type) {
+    const cType = names.type(type);
+    if (cType.kind === 'function')
+        throw new NativeDeclarationException(`A function has no size: ${type}`);
+    return koffi.sizeof(TYPES.type(cType));
+}

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

@@ -0,0 +1,206 @@
+import koffi from 'koffi';
+import { NativeDeclarationException } from '../../exceptions/NativeDeclarationException.js';
+import { primitiveBig, typeText } from '../declarations/Types.js';
+import { toBigInt } from './KoffiTypes.js';
+/**
+ * A 64-bit integer as a number, when it is a safe one
+ * @param value
+ */
+export 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.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
+ */
+export 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' && primitiveBig(target.name)) || (target.kind === 'enum' && primitiveBig(target.base))) {
+            const convert = options.int64 === 'number' ? toSafeNumber : 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
+ */
+export function bindFunction(library, declaration, types, variadicTypes, options = {}) {
+    const type = declaration.type;
+    if (options.async && type.variadic)
+        throw new 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(`The parameter ${parameter.name ?? ''} of ${declaration.name} is ${parameter.direction === 'out' ? '_Out_' : '_Inout_'} but not a pointer (${typeText(parameter.type)})`.replace('  ', ' '));
+        const pointed = options.free && isString(target) ? koffi.pointer(disposableString(target, options.free)) : types.type(parameter.type);
+        return parameter.direction === 'out' ? koffi.out(pointed) : koffi.inout(pointed);
+    });
+    let bound;
+    try {
+        bound = library.func(`__${type.convention}`, declaration.symbol, result, type.variadic ? [...parameters, '...'] : parameters);
+    }
+    catch (error) {
+        throw new 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' && 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);
+            }
+        });
+    };
+}