@lakutata/ffi 0.0.0-stage → 3.1.2

package/dist/cjs/lib/library/NativeLibraryHandle.js

@@ -0,0 +1,540 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NativeLibraryHandle = void 0;
+exports.loadNativeLibrary = loadNativeLibrary;
+const koffi_1 = __importDefault(require("koffi"));
+const NativeDeclarationException_js_1 = require("../../exceptions/NativeDeclarationException.js");
+const NativeLibraryClosedException_js_1 = require("../../exceptions/NativeLibraryClosedException.js");
+const Functions_js_1 = require("../backend/Functions.js");
+const Layout_js_1 = require("../declarations/Layout.js");
+const Parser_js_1 = require("../declarations/Parser.js");
+const Platform_js_1 = require("../declarations/Platform.js");
+const Types_js_1 = require("../declarations/Types.js");
+const Runtime_js_1 = require("../Runtime.js");
+const NativeThreads_js_1 = require("../thread/NativeThreads.js");
+const NativeCallback_js_1 = require("./NativeCallback.js");
+const Resolve_js_1 = require("./Resolve.js");
+/**
+ * The declarations of a library, shared by the libraries loaded with the same declarations: read once, their C types and
+ * their prototypes made once (koffi never frees a type)
+ */
+class LibraryModel {
+    #prototypes;
+    /**
+     * Read the declarations.
+     * @param declarations The C declarations.
+     */
+    constructor(declarations) {
+        this.parser = new Parser_js_1.DeclarationParser(Platform_js_1.CURRENT_PLATFORM);
+        this.names = new Runtime_js_1.TypeNames(this.parser);
+        this.#prototypes = new Map();
+        if (declarations)
+            this.parser.parse(declarations);
+    }
+    /**
+     * A prototype, read once.
+     * @param text The prototype.
+     */
+    prototype(text) {
+        let declaration = this.#prototypes.get(text);
+        if (!declaration) {
+            declaration = this.parser.prototype(text);
+            this.#prototypes.set(text, declaration);
+        }
+        return declaration;
+    }
+}
+const models = new Map();
+/**
+ * The model of declarations, the same for the same text
+ * @param declarations
+ */
+function modelOf(declarations) {
+    let model = models.get(declarations);
+    if (!model) {
+        model = new LibraryModel(declarations);
+        models.set(declarations, model);
+    }
+    return model;
+}
+/**
+ * The value a callback returns to the library when it throws: zero, false, a null pointer
+ * @param type
+ */
+function zeroOf(type) {
+    switch (type.kind) {
+        case 'primitive':
+            if (type.name === 'void')
+                return undefined;
+            if (type.name === 'bool')
+                return false;
+            return 0;
+        case 'enum':
+            return 0;
+        case 'pointer':
+            return null;
+        default:
+            return {};
+    }
+}
+/**
+ * A native library loaded with its declarations, without the container (scripts, tests): its functions, variables and
+ * callbacks, and the native memory read and written with its types. Made by {@link loadNativeLibrary}; a
+ * `NativeLibrary` component holds one.
+ * @example
+ * ```typescript
+ * import {loadNativeLibrary, type NativeLibraryHandle} from '@lakutata/ffi'
+ *
+ * const libc: NativeLibraryHandle = loadNativeLibrary('c', 'typedef struct { int quot; int rem; } div_t;')
+ * const div = libc.func<(numerator: number, denominator: number) => {quot: number, rem: number}>('div_t div(int numerator, int denominator)')
+ * console.log(div(17, 5))
+ * await libc.close()
+ * ```
+ */
+class NativeLibraryHandle {
+    #library;
+    #file;
+    #model;
+    #parser;
+    #names;
+    #options;
+    #functions = new Map();
+    #callbacks = new Set();
+    #allocations = new Set();
+    #frees = new Map();
+    #calls;
+    #threads;
+    //The errno and the last error of Windows of the thread after the last asynchronous call completed in the threads
+    #threadErrno;
+    #threadWindowsError;
+    #pending = 0;
+    #drained = [];
+    #closed = false;
+    /**
+     * Load a library (see {@link loadNativeLibrary}).
+     * @param names Its file names: one, or one by platform; `c` for the C library.
+     * @param declarations Its C declarations: the types, functions and variables its functions use.
+     * @param options Where it is found, how it is closed.
+     */
+    constructor(names, declarations = '', options = {}) {
+        this.#options = options;
+        this.#model = modelOf(declarations);
+        this.#parser = this.#model.parser;
+        this.#names = this.#model.names;
+        const { library, file } = (0, Resolve_js_1.loadLibrary)(names, options);
+        this.#library = library;
+        this.#file = file;
+        if (options.threads !== undefined && (!Number.isInteger(options.threads) || options.threads < 0))
+            throw new NativeDeclarationException_js_1.NativeDeclarationException(`The threads of a library are a number of threads (${options.threads})`);
+        if (options.threads)
+            this.#threads = new NativeThreads_js_1.NativeThreads(file, declarations, options.threads, options.crt);
+        this.#calls = {
+            start: () => {
+                if (this.#closed)
+                    throw new NativeLibraryClosedException_js_1.NativeLibraryClosedException(`The library ${this.#file} is closed`);
+                this.#pending++;
+            },
+            end: () => {
+                if (--this.#pending > 0)
+                    return;
+                const drained = this.#drained;
+                this.#drained = [];
+                for (const resolve of drained)
+                    resolve();
+            }
+        };
+    }
+    /**
+     * The file the library was loaded from.
+     */
+    get file() {
+        return this.#file;
+    }
+    /**
+     * Whether it is closed.
+     */
+    get closed() {
+        return this.#closed;
+    }
+    /**
+     * The asynchronous calls running.
+     */
+    get pending() {
+        return this.#pending;
+    }
+    /**
+     * The worker threads of the library (0: the asynchronous calls run in the thread pool of the runtime).
+     */
+    get threads() {
+        return this.#threads?.count ?? 0;
+    }
+    /**
+     * Settled once the threads of the library have loaded it (at once without threads): rejected with the error of a
+     * thread that could not. The asynchronous calls wait for them anyway.
+     */
+    get ready() {
+        return this.#threads?.ready ?? Promise.resolve();
+    }
+    /**
+     * The constants of its declarations: the values of the enumerations, of the static constants and of the macros whose
+     * value is an integer.
+     */
+    get constants() {
+        return Object.fromEntries(this.#parser.declarations.constants);
+    }
+    /**
+     * Add C declarations to the ones of the library (and of the libraries loaded with the same declarations, which share
+     * them).
+     * @param text The declarations.
+     */
+    declare(text) {
+        this.#parser.parse(text);
+        this.#threads?.declare(text);
+    }
+    /**
+     * A function of the library, from its prototype: the function of koffi itself when nothing has to be converted.
+     * @param prototype Its C prototype, with the types of the declarations: `int sqlite3_open(const char *filename,
+     * _Out_ sqlite3 **db)`.
+     * @param options Whether it is asynchronous, how its strings are freed, how its 64-bit integers are given.
+     * @returns The function.
+     */
+    func(prototype, options = {}) {
+        this.#open();
+        const key = `${prototype}\u0000${JSON.stringify(options)}`;
+        let bound = this.#functions.get(key);
+        if (!bound) {
+            bound = this.#bind(this.#model.prototype(prototype), options, prototype, false);
+            this.#functions.set(key, bound);
+        }
+        return bound;
+    }
+    /**
+     * A function of the declarations, by its name.
+     * @param name Its name.
+     * @param options Whether it is asynchronous, how its strings are freed, how its 64-bit integers are given.
+     * @returns The function.
+     */
+    function(name, options = {}) {
+        this.#open();
+        const declaration = this.#parser.declarations.functions.get(name);
+        if (!declaration)
+            throw new NativeDeclarationException_js_1.NativeDeclarationException(`The function ${name} is not declared`);
+        const key = `\u0001${name}\u0000${JSON.stringify(options)}`;
+        let bound = this.#functions.get(key);
+        if (!bound) {
+            bound = this.#bind(declaration, options, name, true);
+            this.#functions.set(key, bound);
+        }
+        return bound;
+    }
+    /**
+     * A variable the library exports: declared in the declarations (`extern const char sqlite3_version[];`), or by the
+     * declaration given.
+     * @param declaration Its name, or its declaration.
+     * @returns Its address, and the functions reading and writing its value.
+     */
+    variable(declaration) {
+        this.#open();
+        let name = declaration.trim();
+        if (!/^[A-Za-z_]\w*$/.test(name)) {
+            const before = new Set(this.#parser.declarations.variables.keys());
+            this.#parser.parse(/;\s*$/.test(name) ? name : `${name};`);
+            name = [...this.#parser.declarations.variables.keys()].find((variable) => !before.has(variable)) ?? name.match(/(\w+)\s*(\[[^\]]*\])?\s*;?\s*$/)?.[1] ?? name;
+        }
+        const variable = this.#parser.declarations.variables.get(name);
+        if (!variable)
+            throw new NativeDeclarationException_js_1.NativeDeclarationException(`The variable ${name} is not declared`);
+        let address;
+        try {
+            address = this.#library.symbol(variable.symbol);
+        }
+        catch (error) {
+            throw new NativeDeclarationException_js_1.NativeDeclarationException(`The variable ${name} is not in the library (${variable.symbol}): ${error.message}`);
+        }
+        const type = variable.type;
+        const unknownLength = type.kind === 'array' && type.length === 0;
+        const converter = Runtime_js_1.TYPES.converter(type);
+        return {
+            address: address,
+            get: () => {
+                this.#open();
+                if (unknownLength) {
+                    const element = type.of;
+                    return (element.kind === 'primitive' && element.name === 'char' ? koffi_1.default.decode.string(address) : address);
+                }
+                const value = koffi_1.default.decode(address, Runtime_js_1.TYPES.type(type));
+                return (converter?.fromNative ? converter.fromNative(value) : value);
+            },
+            set: (value) => {
+                this.#open();
+                if (variable.constant)
+                    throw new NativeDeclarationException_js_1.NativeDeclarationException(`The variable ${name} is const`);
+                if (unknownLength)
+                    throw new NativeDeclarationException_js_1.NativeDeclarationException(`The array ${name} has no length: write its elements through its address`);
+                koffi_1.default.encode(address, Runtime_js_1.TYPES.type(type), converter?.toNative ? converter.toNative(value) : value);
+            }
+        };
+    }
+    /**
+     * A persistent callback: a JS function the library can call at any time, released by `release()` or when the
+     * library is closed.
+     * @param type Its type: the name of a pointer-to-function type of the declarations (`vendor_log`), or its prototype
+     * (`void vendor_log(int level, const char *message)`).
+     * @param callback The JS function.
+     * @returns The callback, whose `pointer` is given to the library.
+     */
+    callback(type, callback) {
+        this.#open();
+        let prototype;
+        if (type.includes('(')) {
+            prototype = this.#parser.prototype(type).type;
+        }
+        else {
+            const named = this.#names.type(type);
+            const target = named.kind === 'pointer' ? named.to : named;
+            if (target.kind !== 'function')
+                throw new NativeDeclarationException_js_1.NativeDeclarationException(`The type ${type} is not a function type (${(0, Types_js_1.typeText)(named)})`);
+            prototype = target;
+        }
+        const onError = this.#options.onCallbackError ?? ((error) => console.error('A callback of a native library threw:', error));
+        const zero = zeroOf(prototype.result);
+        const safe = (...args) => {
+            try {
+                return callback(...args);
+            }
+            catch (error) {
+                onError(error);
+                return zero;
+            }
+        };
+        const pointer = koffi_1.default.register((0, Functions_js_1.convertedCallback)(prototype, Runtime_js_1.TYPES, safe), koffi_1.default.pointer(Runtime_js_1.TYPES.prototype(prototype)));
+        const registered = new NativeCallback_js_1.NativeCallback(pointer, (released) => this.#callbacks.delete(released));
+        this.#callbacks.add(registered);
+        return registered;
+    }
+    /**
+     * Read native memory, as a type of the declarations: a value, or an array of values.
+     * @param pointer The address.
+     * @param type The type: `int`, `struct timeval`, `char *` (a string).
+     * @param count The number of values, for an array.
+     * @returns The value, or the array.
+     */
+    read(pointer, type, count) {
+        this.#open();
+        return (0, Runtime_js_1.readNative)(this.#names, pointer, type, count);
+    }
+    /**
+     * Write a value to native memory, as a type of the declarations.
+     * @param pointer The address.
+     * @param type The type.
+     * @param value The value.
+     */
+    write(pointer, type, value) {
+        this.#open();
+        (0, Runtime_js_1.writeNative)(this.#names, pointer, type, value);
+    }
+    /**
+     * The size of a type of the declarations, in bytes.
+     * @param type The type.
+     */
+    sizeOf(type) {
+        return (0, Runtime_js_1.typeSize)(this.#names, type);
+    }
+    /**
+     * The offset of a member of a struct of the declarations, in bytes.
+     * @param type The struct.
+     * @param member The member.
+     */
+    offsetOf(type, member) {
+        const record = this.#names.type(type);
+        if (record.kind !== 'struct' && record.kind !== 'union')
+            throw new NativeDeclarationException_js_1.NativeDeclarationException(`${type} is not a struct or a union`);
+        const placed = (0, Layout_js_1.layoutOf)(record, Platform_js_1.CURRENT_PLATFORM).members.find((candidate) => candidate.member.name === member);
+        if (!placed)
+            throw new NativeDeclarationException_js_1.NativeDeclarationException(`${type} has no member ${member}`);
+        return placed.offset;
+    }
+    /**
+     * Allocate native memory for values of a type of the declarations: memory that does not move, which the library can
+     * keep; freed by `free()`, or when the library is closed.
+     * @param type The type.
+     * @param count The number of values.
+     * @returns Its address.
+     */
+    alloc(type, count = 1) {
+        this.#open();
+        const pointer = (0, Runtime_js_1.allocateNative)(this.#names, type, count);
+        this.#allocations.add(pointer);
+        return pointer;
+    }
+    /**
+     * Free memory allocated by `alloc()`.
+     * @param pointer Its address.
+     */
+    free(pointer) {
+        const address = (0, Runtime_js_1.checkedPointer)(pointer, 'free');
+        this.#allocations.delete(address);
+        (0, Runtime_js_1.freeNative)(address);
+    }
+    /**
+     * The errno of the last call of this thread (on Windows, the one of the C library given by the `crt` option); with
+     * threads, the one of the thread of the last asynchronous call completed (reliable with one thread, or when the
+     * asynchronous calls are awaited one at a time).
+     */
+    errno() {
+        return this.#threadErrno ?? (0, Runtime_js_1.nativeErrno)(this.#options.crt);
+    }
+    /**
+     * The last error of the Windows API (GetLastError) after the last call of this thread; with threads, the one of the
+     * thread of the last asynchronous call completed; undefined on the other systems.
+     */
+    windowsError() {
+        return this.#threadWindowsError ?? (0, Runtime_js_1.nativeWindowsError)();
+    }
+    /**
+     * The asynchronous calls running, once they have all returned.
+     * @param timeout How long to wait at most, in milliseconds.
+     * @returns Whether they have all returned.
+     */
+    drain(timeout = Infinity) {
+        if (!this.#pending)
+            return Promise.resolve(true);
+        return new Promise((resolve) => {
+            const timer = Number.isFinite(timeout) ? setTimeout(() => resolve(false), timeout) : undefined;
+            this.#drained.push(() => {
+                if (timer)
+                    clearTimeout(timer);
+                resolve(true);
+            });
+        });
+    }
+    /**
+     * Close the library: new asynchronous calls are refused, the running ones awaited (a worker thread stopped during
+     * one crashes Bun), the callbacks released, the memory of `alloc()` freed, the library unloaded (unless kept
+     * loaded; musl never unloads). Its functions must not be called any more: a function of an unloaded library ends
+     * the process. When calls still run after the timeout, the ones in the thread pool go on, the ones in the threads
+     * of the library are rejected (their threads end once they return), and the library, its callbacks and its memory
+     * are left as they are: a call returning into an unloaded library, or calling a released callback, would end the
+     * process.
+     * @param timeout How long to wait for the asynchronous calls, in milliseconds.
+     */
+    async close(timeout = 10000) {
+        if (this.#closed)
+            return;
+        this.#closed = true;
+        //Decided before the threads close: they reject the calls still running, which then no longer count
+        const drained = await this.drain(timeout);
+        await this.#threads?.close();
+        this.#functions.clear();
+        if (!drained)
+            return;
+        for (const callback of [...this.#callbacks])
+            callback.release();
+        for (const pointer of this.#allocations)
+            (0, Runtime_js_1.freeNative)(pointer);
+        this.#allocations.clear();
+        if (!this.#options.keepLoaded)
+            this.#library.unload();
+    }
+    /**
+     * Throws once the library is closed
+     */
+    #open() {
+        if (this.#closed)
+            throw new NativeLibraryClosedException_js_1.NativeLibraryClosedException(`The library ${this.#file} is closed`);
+    }
+    /**
+     * A function bound, with its options; an asynchronous function of a library with threads, called in them
+     * @param declaration
+     * @param options
+     * @param text its prototype, or the name of the declared function
+     * @param named
+     */
+    #bind(declaration, options, text, named) {
+        if (options.async && this.#threads)
+            return this.#threaded(this.#threads, { declaration: text, named: named, options: { free: options.free, int64: options.int64 }, type: declaration });
+        return (0, Functions_js_1.bindFunction)(this.#library, declaration, Runtime_js_1.TYPES, (text) => this.#names.koffi(text), {
+            async: options.async,
+            int64: options.int64,
+            calls: this.#calls,
+            ...options.free ? { free: this.#freeFunction(options.free) } : {}
+        });
+    }
+    /**
+     * An asynchronous function called in the threads of the library, counted as its other asynchronous calls
+     * @param threads
+     * @param fn
+     */
+    #threaded(threads, fn) {
+        threads.bind(fn);
+        return (...args) => {
+            try {
+                this.#calls.start();
+            }
+            catch (error) {
+                return Promise.reject(error);
+            }
+            return threads.call(fn, args).then((result) => {
+                this.#threadErrno = result.errno;
+                this.#threadWindowsError = result.windowsError;
+                this.#calls.end();
+                return result.value;
+            }, (error) => {
+                this.#calls.end();
+                throw error;
+            });
+        };
+    }
+    /**
+     * The function freeing the strings of a function: one of the library, or free() of the C library
+     * @param free
+     */
+    #freeFunction(free) {
+        if (free === true)
+            return (pointer) => koffi_1.default.free(pointer);
+        let found = this.#frees.get(free);
+        if (!found) {
+            try {
+                found = this.#library.func(free, 'void', ['void *']);
+            }
+            catch (error) {
+                throw new NativeDeclarationException_js_1.NativeDeclarationException(`The function ${free} freeing the strings is not in the library: ${error.message}`);
+            }
+            this.#frees.set(free, found);
+        }
+        return found;
+    }
+}
+exports.NativeLibraryHandle = NativeLibraryHandle;
+/**
+ * Load a native library with its C declarations, without the container (scripts, tests); in an application, declare a
+ * `NativeLibrary` component instead. The library is looked for in the directories of `search`, then where the system
+ * looks for libraries.
+ * @param names Its file names: one (`sqlite3`, completed as the platform names libraries), one by platform
+ * (`{darwin: 'libsqlite3.dylib', linux: 'libsqlite3.so.0', win32: 'winsqlite3.dll'}`), or `c` for the C library.
+ * @param declarations Its C declarations: the types its functions use, its functions, its variables, its constants.
+ * @param options Where it is found, how it is closed.
+ * @returns The library.
+ * @throws {NativeLibraryNotFoundException} When it cannot be loaded (the message lists what was tried).
+ * @throws {NativeDeclarationException} When the declarations cannot be read.
+ * @example
+ * ```typescript
+ * import {loadNativeLibrary, type Out, type Pointer} from '@lakutata/ffi'
+ *
+ * const sqlite = loadNativeLibrary({darwin: 'libsqlite3.dylib', linux: 'libsqlite3.so.0', win32: 'winsqlite3.dll'}, `
+ *     typedef struct sqlite3 sqlite3;
+ *     #define SQLITE_OK 0
+ * `)
+ * const open = sqlite.func<(filename: string, db: Out<Pointer>) => number>('int sqlite3_open(const char *filename, _Out_ sqlite3 **db)')
+ * const close = sqlite.func<(db: Pointer) => number>('int sqlite3_close(sqlite3 *db)')
+ * const db: Out<Pointer> = [null]
+ * if (open(':memory:', db) === Number(sqlite.constants.SQLITE_OK)) close(db[0]!)
+ * await sqlite.close()
+ * ```
+ */
+function loadNativeLibrary(names, declarations = '', options = {}) {
+    return new NativeLibraryHandle(names, declarations, options);
+}

package/dist/cjs/lib/library/Resolve.d.ts

@@ -0,0 +1,49 @@
+import { type LibraryHandle } from 'koffi';
+/**
+ * The file of a library: one name for every platform, or one by platform (the names of process.platform, `default`
+ * for the others). A name without a directory and without an extension is completed as the platform names its
+ * libraries (`sqlite3`: `libsqlite3.dylib`, `libsqlite3.so`, `sqlite3.dll`); `c` and `m` are the C library and its
+ * mathematical functions, found where each system has them
+ */
+export type LibraryNames = string | Partial<Record<NodeJS.Platform | 'default', string | readonly string[]>>;
+/**
+ * Where a library is looked for
+ */
+export interface ResolveOptions {
+    /**
+     * The file itself: the only one tried when given (an alias of the application can start it)
+     */
+    readonly path?: string;
+    /**
+     * The directories tried first, in their order
+     */
+    readonly search?: readonly string[];
+    /**
+     * The directory of the libraries of a packaged application, tried after the search directories
+     */
+    readonly packaged?: string;
+}
+/**
+ * The file names a name gives on a system: the name itself when it has a directory or an extension, else the names the
+ * system gives libraries
+ * @param name
+ * @param os
+ */
+export declare function fileNames(name: string, os?: NodeJS.Platform): string[];
+/**
+ * The names of a library on a system
+ * @param names
+ * @param os
+ */
+export declare function libraryNames(names: LibraryNames, os?: NodeJS.Platform): string[];
+/**
+ * Load a library: the file given; else each name in the search directories, in the directory of a packaged
+ * application, then where the system looks for libraries (dlopen, LoadLibrary)
+ * @param names
+ * @param options
+ * @returns The library and the file it was loaded from.
+ */
+export declare function loadLibrary(names: LibraryNames, options?: ResolveOptions): {
+    library: LibraryHandle;
+    file: string;
+};