@lakutata/ffi 0.0.0-stage → 3.1.2

package/dist/esm/components/NativeLibrary.js

@@ -0,0 +1,338 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+import path from 'node:path';
+import { Component, DTO, isPackaged, resourcesPath } from '@lakutata/core';
+import { Configurable } from '@lakutata/core/decorator/di';
+import { libraryOptionsOf } from '../decorators/Library.js';
+import { nativeMembersOf } from '../decorators/Native.js';
+import { NativeDeclarationException } from '../exceptions/NativeDeclarationException.js';
+import { NativeLibraryClosedException } from '../exceptions/NativeLibraryClosedException.js';
+import { NativeLibraryHandle } from '../lib/library/NativeLibraryHandle.js';
+/**
+ * A native library: a component holding a library loaded with its C declarations (`@Library`), its functions on its
+ * properties (`@Native`), its variables (`@NativeVariable`). Write one subclass for each library and register it in the
+ * components of the application; it is loaded when it is created, and destroyed with the application: the asynchronous
+ * calls running are awaited, its callbacks released, the library unloaded.
+ *
+ * In a packaged application, the library is also looked for in the directory `native` of the resources (put it there
+ * with `lakutata.resources` of the package.json). The exceptions thrown by its persistent callbacks are its `error`
+ * events (written to the log of the application when nothing listens to them).
+ * @example
+ * ```typescript
+ * import {Application} from 'lakutata'
+ * import {buildNativeLibraryOptions, Library, Native, NativeLibrary, type Out, type Pointer} from '@lakutata/ffi'
+ *
+ * @Library({
+ *     names: {darwin: 'libsqlite3.dylib', linux: 'libsqlite3.so.0', win32: 'winsqlite3.dll'},
+ *     declarations: `
+ *         typedef struct sqlite3 sqlite3;
+ *         #define SQLITE_OK 0
+ *     `
+ * })
+ * export class SQLite extends NativeLibrary {
+ *     @Native('const char *sqlite3_libversion(void)')
+ *     public readonly libversion: () => string
+ *
+ *     @Native('int sqlite3_open(const char *filename, _Out_ sqlite3 **db)')
+ *     public readonly open: (filename: string, db: Out<Pointer>) => number
+ *
+ *     @Native('int sqlite3_close(sqlite3 *db)')
+ *     public readonly close: (db: Pointer) => number
+ * }
+ *
+ * Application
+ *     .run(() => ({
+ *         id: 'store.app',
+ *         name: 'Store',
+ *         components: {
+ *             sqlite: buildNativeLibraryOptions(SQLite)
+ *         }
+ *     }))
+ *     .onLaunched(async (app: Application): Promise<void> => {
+ *         const sqlite: SQLite = await app.getObject('sqlite')
+ *         console.log(sqlite.libversion())
+ *     })
+ * ```
+ */
+export class NativeLibrary extends Component {
+    #handle;
+    /**
+     * Load the library and bind its functions and variables to their properties.
+     * @protected
+     */
+    async init() {
+        const library = libraryOptionsOf(this.constructor);
+        if (!library)
+            throw new NativeDeclarationException(`${this.constructor.name} has no @Library: give the names of its library and its declarations`);
+        const resources = isPackaged() ? resourcesPath() : undefined;
+        this.#handle = new NativeLibraryHandle(library.names, library.declarations ?? '', {
+            path: this.path,
+            search: [...this.search ?? [], ...library.search ?? []],
+            packaged: resources ? path.join(resources, 'native') : undefined,
+            keepLoaded: this.keepLoaded,
+            crt: library.crt,
+            threads: this.threads ?? library.threads ?? 0,
+            onCallbackError: (error) => this.#callbackError(error)
+        });
+        //The threads have loaded the library (a thread that could not fails the creation)
+        try {
+            await this.#handle.ready;
+        }
+        catch (error) {
+            await this.#handle.close(0);
+            this.#handle = undefined;
+            throw error;
+        }
+        for (const [key, member] of nativeMembersOf(Object.getPrototypeOf(this)))
+            this.#bindMember(key, member);
+    }
+    /**
+     * Close the library: the asynchronous calls running awaited, the callbacks released, the library unloaded (kept,
+     * with its callbacks and its memory, when calls still run after `drainTimeout`); its properties throw from then on.
+     * @protected
+     */
+    async destroy() {
+        const handle = this.#handle;
+        if (!handle)
+            return;
+        for (const [key, member] of nativeMembersOf(Object.getPrototypeOf(this)))
+            this.#closeMember(key, member, handle.file);
+        await handle.close(this.drainTimeout ?? 10000);
+    }
+    /**
+     * The file the library was loaded from.
+     */
+    get file() {
+        return this.#library().file;
+    }
+    /**
+     * The asynchronous calls running.
+     */
+    get pending() {
+        return this.#library().pending;
+    }
+    /**
+     * The worker threads of the library (0: its asynchronous calls run in the thread pool of the runtime).
+     */
+    get threadCount() {
+        return this.#library().threads;
+    }
+    /**
+     * The constants of the declarations: the values of the enumerations, of the static constants and of the macros
+     * whose value is an integer.
+     */
+    get constants() {
+        return this.#library().constants;
+    }
+    /**
+     * A function of the library bound from its prototype, besides the ones of the properties.
+     * @param prototype Its C prototype, with the types of the declarations.
+     * @param options Whether it is asynchronous, how its strings are freed, how its 64-bit integers are given.
+     * @returns The function.
+     */
+    func(prototype, options = {}) {
+        return this.#library().func(prototype, options);
+    }
+    /**
+     * A variable the library exports, besides the ones of the properties.
+     * @param declaration Its name in the declarations, or its declaration.
+     * @returns Its address, and the functions reading and writing its value.
+     */
+    variable(declaration) {
+        return this.#library().variable(declaration);
+    }
+    /**
+     * A persistent callback: a JS function the library can call at any time, released by `release()` or when the
+     * component is destroyed. Its exceptions are `error` events of the component.
+     * @param type The name of a pointer-to-function type of the declarations, or its prototype.
+     * @param callback The JS function.
+     * @returns The callback, whose `pointer` is given to the library.
+     */
+    callback(type, callback) {
+        return this.#library().callback(type, callback);
+    }
+    /**
+     * 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) {
+        return this.#library().read(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.#library().write(pointer, type, value);
+    }
+    /**
+     * The size of a type of the declarations, in bytes.
+     * @param type The type.
+     */
+    sizeOf(type) {
+        return this.#library().sizeOf(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) {
+        return this.#library().offsetOf(type, member);
+    }
+    /**
+     * Allocate native memory for values of a type of the declarations, which the library can keep; freed by `free()`,
+     * or when the component is destroyed.
+     * @param type The type.
+     * @param count The number of values.
+     * @returns Its address.
+     */
+    alloc(type, count = 1) {
+        return this.#library().alloc(type, count);
+    }
+    /**
+     * Free memory allocated by `alloc()`.
+     * @param pointer Its address.
+     */
+    free(pointer) {
+        this.#library().free(pointer);
+    }
+    /**
+     * The errno of the last call of this thread (on Windows, the one of the C library of `@Library`, ucrtbase.dll by
+     * default); with threads, the one of the thread of the last asynchronous call completed.
+     */
+    errno() {
+        return this.#library().errno();
+    }
+    /**
+     * The last error of the Windows API 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.#library().windowsError();
+    }
+    /**
+     * The library, once loaded
+     */
+    #library() {
+        if (!this.#handle)
+            throw new NativeLibraryClosedException(`The library of ${this.constructor.name} is not loaded`);
+        return this.#handle;
+    }
+    /**
+     * A function or a variable bound to its property
+     * @param key
+     * @param member
+     */
+    #bindMember(key, member) {
+        const handle = this.#handle;
+        const declaration = member.declaration ?? key;
+        const named = /^[A-Za-z_]\w*$/.test(declaration);
+        if (member.kind === 'function') {
+            const bound = named ? handle.function(declaration, member.options) : handle.func(declaration, member.options);
+            Object.defineProperty(this, key, { value: bound, writable: false, enumerable: true, configurable: true });
+            return;
+        }
+        const variable = handle.variable(declaration);
+        Object.defineProperty(this, key, {
+            get: () => variable.get(),
+            set: (value) => variable.set(value),
+            enumerable: true,
+            configurable: true
+        });
+    }
+    /**
+     * A property of a closed library: throwing (an asynchronous function rejecting)
+     * @param key
+     * @param member
+     * @param file
+     */
+    #closeMember(key, member, file) {
+        const closed = () => new NativeLibraryClosedException(`The library ${file} is closed: ${this.constructor.name}.${key} cannot be used`);
+        if (member.kind === 'function') {
+            const value = member.options.async ? () => Promise.reject(closed()) : () => {
+                throw closed();
+            };
+            Object.defineProperty(this, key, { value: value, writable: false, enumerable: true, configurable: true });
+            return;
+        }
+        const fail = () => {
+            throw closed();
+        };
+        Object.defineProperty(this, key, { get: fail, set: fail, enumerable: true, configurable: true });
+    }
+    /**
+     * An exception of a persistent callback: an error event, or the log of the application when nothing listens
+     * @param error
+     */
+    #callbackError(error) {
+        if (this.listenerCount('error')) {
+            this.emit('error', error);
+            return;
+        }
+        const message = `A callback of the native library ${this.#handle?.file ?? this.constructor.name} threw`;
+        this.getModule().getObject('log').then((log) => log.error(error, message), () => console.error(`${message}:`, error));
+    }
+}
+__decorate([
+    Configurable(DTO.String().optional()),
+    __metadata("design:type", String)
+], NativeLibrary.prototype, "path", void 0);
+__decorate([
+    Configurable(DTO.Array().items(DTO.String()).optional()),
+    __metadata("design:type", Array)
+], NativeLibrary.prototype, "search", void 0);
+__decorate([
+    Configurable(DTO.Boolean().optional()),
+    __metadata("design:type", Boolean)
+], NativeLibrary.prototype, "keepLoaded", void 0);
+__decorate([
+    Configurable(DTO.Number().min(0).optional()),
+    __metadata("design:type", Number)
+], NativeLibrary.prototype, "drainTimeout", void 0);
+__decorate([
+    Configurable(DTO.Number().integer().min(0).optional()),
+    __metadata("design:type", Number)
+], NativeLibrary.prototype, "threads", void 0);
+/**
+ * Build the declaration of a library component, for the `components` of an application.
+ * @param library The `NativeLibrary` subclass of the library.
+ * @param options Where it is found (a file, directories searched first), whether it stays loaded, how long its
+ * destruction waits for its asynchronous calls.
+ * @returns The component declaration.
+ * @example
+ * ```typescript
+ * import {Application} from 'lakutata'
+ * import {buildNativeLibraryOptions, Library, Native, NativeLibrary} from '@lakutata/ffi'
+ *
+ * @Library({names: 'vendor'})
+ * class Vendor extends NativeLibrary {
+ *     @Native('int vendor_version(void)')
+ *     public readonly version: () => number
+ * }
+ *
+ * Application.run(() => ({
+ *     id: 'devices.app',
+ *     name: 'Devices',
+ *     components: {
+ *         //The library shipped with the application: an alias, or a path relative to the working directory
+ *         vendor: buildNativeLibraryOptions(Vendor, {search: ['@data/native']})
+ *     }
+ * }))
+ * ```
+ */
+export function buildNativeLibraryOptions(library, options = {}) {
+    return { class: library, ...options };
+}

package/dist/esm/decorators/Library.js

@@ -0,0 +1,40 @@
+const libraries = new WeakMap();
+/**
+ * Declare a native library on a `NativeLibrary` subclass: its file names, the directories it is looked for in, its C
+ * declarations. Its functions are declared on its properties by `@Native`, its variables by `@NativeVariable`.
+ * @param options Its names, its search directories, its declarations.
+ * @returns The class decorator.
+ * @example
+ * ```typescript
+ * import {Library, Native, NativeLibrary} from '@lakutata/ffi'
+ *
+ * @Library({
+ *     names: {darwin: 'libz.dylib', linux: 'libz.so.1', win32: 'zlib1.dll'},
+ *     declarations: 'typedef unsigned long uLong;'
+ * })
+ * export class Zlib extends NativeLibrary {
+ *     @Native('const char *zlibVersion(void)')
+ *     public readonly zlibVersion: () => string
+ *
+ *     @Native('uLong crc32(uLong crc, const unsigned char *buffer, unsigned int length)')
+ *     public readonly crc32: (crc: bigint | number, buffer: Buffer, length: number) => bigint
+ * }
+ * ```
+ */
+export function Library(options) {
+    return (target) => {
+        libraries.set(target, options);
+    };
+}
+/**
+ * The library declared on a class or on the nearest of its parent classes
+ * @param target
+ */
+export function libraryOptionsOf(target) {
+    for (let current = target; current && current !== Function.prototype; current = Object.getPrototypeOf(current)) {
+        const options = libraries.get(current);
+        if (options)
+            return options;
+    }
+    return undefined;
+}

package/dist/esm/decorators/Native.js

@@ -0,0 +1,85 @@
+const members = new WeakMap();
+/**
+ * Record a member on the prototype of a class
+ * @param target
+ * @param key
+ * @param member
+ */
+function record(target, key, member) {
+    if (typeof key !== 'string')
+        throw new TypeError('A native function or variable is declared on a property with a string name');
+    let own = members.get(target);
+    if (!own)
+        members.set(target, own = new Map());
+    own.set(key, member);
+}
+/**
+ * Declare a function of the library on a property of a `NativeLibrary` subclass: the property gets the function once
+ * the component is created (the function of koffi itself when nothing is converted), and a function throwing once it
+ * is destroyed. The TypeScript type of the property is the one of the function.
+ * @param declaration Its C prototype (`int sqlite3_open(const char *filename, _Out_ sqlite3 **db)`), or the name of a
+ * function of the declarations of the library; by default the function of the declarations named as the property.
+ * @param options Whether it runs in a thread of the pool (returning a promise), the function freeing the strings it
+ * gives, its 64-bit integers as numbers.
+ * @returns The property decorator.
+ * @example
+ * ```typescript
+ * import {Library, Native, NativeLibrary, type Out, type Pointer} from '@lakutata/ffi'
+ *
+ * @Library({
+ *     names: {darwin: 'libsqlite3.dylib', linux: 'libsqlite3.so.0', win32: 'winsqlite3.dll'},
+ *     declarations: `
+ *         typedef struct sqlite3 sqlite3;
+ *         int sqlite3_close(sqlite3 *db);
+ *     `
+ * })
+ * export class SQLite extends NativeLibrary {
+ *     @Native('int sqlite3_open(const char *filename, _Out_ sqlite3 **db)')
+ *     public readonly open: (filename: string, db: Out<Pointer>) => number
+ *
+ *     //The function of the declarations named as the property
+ *     @Native()
+ *     public readonly sqlite3_close: (db: Pointer) => number
+ *
+ *     @Native('int sqlite3_exec(sqlite3 *db, const char *sql, void *callback, void *context, _Out_ char **error)', {async: true, free: 'sqlite3_free'})
+ *     public readonly exec: (db: Pointer, sql: string, callback: null, context: null, error: Out<string>) => Promise<number>
+ * }
+ * ```
+ */
+export function Native(declaration, options = {}) {
+    return (target, key) => record(target, key, { kind: 'function', declaration: declaration, options: options });
+}
+/**
+ * Declare a variable the library exports on a property of a `NativeLibrary` subclass: reading the property reads the
+ * variable, writing it writes the variable (refused for a const one).
+ * @param declaration Its declaration (`extern const char sqlite3_version[]`), or the name of a variable of the
+ * declarations of the library; by default the variable of the declarations named as the property.
+ * @returns The property decorator.
+ * @example
+ * ```typescript
+ * import {Library, NativeLibrary, NativeVariable} from '@lakutata/ffi'
+ *
+ * @Library({names: {darwin: 'libsqlite3.dylib', linux: 'libsqlite3.so.0', win32: 'winsqlite3.dll'}})
+ * export class SQLiteVersion extends NativeLibrary {
+ *     @NativeVariable('extern const char sqlite3_version[]')
+ *     public readonly version: string
+ * }
+ * ```
+ */
+export function NativeVariable(declaration) {
+    return (target, key) => record(target, key, { kind: 'variable', declaration: declaration });
+}
+/**
+ * The native members of a class and of its parent classes (a subclass replacing a member of its parent)
+ * @param prototype
+ */
+export function nativeMembersOf(prototype) {
+    const chain = [];
+    for (let current = prototype; current && current !== Object.prototype; current = Object.getPrototypeOf(current))
+        chain.unshift(current);
+    const all = new Map();
+    for (const current of chain)
+        for (const [key, member] of members.get(current) ?? [])
+            all.set(key, member);
+    return all;
+}

package/dist/esm/exceptions/NativeDeclarationException.js

@@ -0,0 +1,15 @@
+import { Exception } from '@lakutata/core';
+/**
+ * Thrown when C declarations or a function prototype cannot be read: its message gives the line and the column, what
+ * was found and what was expected (a type not declared, a construct not supported such as a macro or `long double`).
+ * Its `errno` is `'E_NATIVE_DECLARATION'`.
+ */
+export class NativeDeclarationException extends Exception {
+    constructor() {
+        super(...arguments);
+        /**
+         * `'E_NATIVE_DECLARATION'`.
+         */
+        this.errno = 'E_NATIVE_DECLARATION';
+    }
+}

package/dist/esm/exceptions/NativeLibraryClosedException.js

@@ -0,0 +1,15 @@
+import { Exception } from '@lakutata/core';
+/**
+ * Thrown when a function, a variable or a callback of a library is used once the library is closed (its component
+ * destroyed, or `close()` called): calling a function of an unloaded library would end the process. Its `errno` is
+ * `'E_NATIVE_LIBRARY_CLOSED'`.
+ */
+export class NativeLibraryClosedException extends Exception {
+    constructor() {
+        super(...arguments);
+        /**
+         * `'E_NATIVE_LIBRARY_CLOSED'`.
+         */
+        this.errno = 'E_NATIVE_LIBRARY_CLOSED';
+    }
+}

package/dist/esm/exceptions/NativeLibraryNotFoundException.js

@@ -0,0 +1,14 @@
+import { Exception } from '@lakutata/core';
+/**
+ * Thrown when a library cannot be loaded: its message lists each file tried and why it could not be loaded (not found,
+ * built for another architecture, a library it needs missing). Its `errno` is `'E_NATIVE_LIBRARY_NOT_FOUND'`.
+ */
+export class NativeLibraryNotFoundException extends Exception {
+    constructor() {
+        super(...arguments);
+        /**
+         * `'E_NATIVE_LIBRARY_NOT_FOUND'`.
+         */
+        this.errno = 'E_NATIVE_LIBRARY_NOT_FOUND';
+    }
+}

package/dist/esm/exceptions/NativeMemoryException.js

@@ -0,0 +1,14 @@
+import { Exception } from '@lakutata/core';
+/**
+ * Thrown when native memory cannot be read or written as asked: a null pointer, a negative length, a view of native
+ * memory where the runtime forbids it (Electron). Its `errno` is `'E_NATIVE_MEMORY'`.
+ */
+export class NativeMemoryException extends Exception {
+    constructor() {
+        super(...arguments);
+        /**
+         * `'E_NATIVE_MEMORY'`.
+         */
+        this.errno = 'E_NATIVE_MEMORY';
+    }
+}

package/dist/esm/exports/FFI.js

@@ -0,0 +1,10 @@
+export { NativeDeclarationException } from '../exceptions/NativeDeclarationException.js';
+export { NativeLibraryNotFoundException } from '../exceptions/NativeLibraryNotFoundException.js';
+export { NativeLibraryClosedException } from '../exceptions/NativeLibraryClosedException.js';
+export { NativeMemoryException } from '../exceptions/NativeMemoryException.js';
+export { NativeCallback } from '../lib/library/NativeCallback.js';
+export { loadNativeLibrary, NativeLibraryHandle } from '../lib/library/NativeLibraryHandle.js';
+export { allocMemory, freeMemory, lastErrno, lastWindowsError, readArray, readBuffer, readCString, readValue, readWString, sizeOf, viewBuffer, writeValue } from '../lib/Memory.js';
+export { Library } from '../decorators/Library.js';
+export { Native, NativeVariable } from '../decorators/Native.js';
+export { buildNativeLibraryOptions, NativeLibrary } from '../components/NativeLibrary.js';

package/dist/esm/exports/Generator.js

@@ -0,0 +1,2 @@
+export { generateNativeLibrary } from '../lib/generator/Generator.js';
+export { defaultCompiler } from '../lib/generator/Preprocessor.js';