@lakutata/ffi 0.0.0-stage → 3.1.2

package/dist/cjs/lib/generator/TypeScriptTypes.d.ts

@@ -0,0 +1,35 @@
+import { type CType, type FunctionType, type RecordType } from '../declarations/Types.js';
+/**
+ * Where a value is: given to a native function (a parameter, the result of a JS callback), or given by it (a result, a
+ * member of a struct, an argument a JS callback receives)
+ */
+export type Flow = 'given' | 'received';
+/**
+ * The TypeScript types of C types, as the package converts their values
+ */
+export declare class TypeScriptTypes {
+    #private;
+    /**
+     * Types for the declarations of a library.
+     * @param names The TypeScript names of its structs and unions.
+     */
+    constructor(names: ReadonlyMap<CType, string>);
+    /**
+     * The TypeScript type of a value of a C type.
+     * @param type The C type.
+     * @param flow Whether the value is given to the native code or received from it.
+     */
+    type(type: CType, flow: Flow): string;
+    /**
+     * The TypeScript type of a function: of a native function, or of a JS callback the native code calls.
+     * @param type The function type.
+     * @param callback Whether it is a JS callback (its arguments received, its result given).
+     */
+    functionType(type: FunctionType, callback?: boolean): string;
+    /**
+     * The members of a struct or a union, as the lines of an interface (or of an object type).
+     * @param record The struct or the union.
+     * @param indent The indentation of the lines.
+     */
+    members(record: RecordType, indent: string): string[];
+}

package/dist/cjs/lib/generator/TypeScriptTypes.js

@@ -0,0 +1,153 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TypeScriptTypes = void 0;
+const Types_js_1 = require("../declarations/Types.js");
+/**
+ * The words TypeScript reserves: not names of parameters
+ */
+const RESERVED = new Set([
+    'break', 'case', 'catch', 'class', 'const', 'continue', 'debugger', 'default', 'delete', 'do', 'else', 'enum', 'export', 'extends', 'false',
+    'finally', 'for', 'function', 'if', 'import', 'in', 'instanceof', 'new', 'null', 'return', 'super', 'switch', 'this', 'throw', 'true', 'try',
+    'typeof', 'var', 'void', 'while', 'with', 'as', 'implements', 'interface', 'let', 'package', 'private', 'protected', 'public', 'static',
+    'yield', 'await', 'arguments', 'eval'
+]);
+/**
+ * The typed arrays of the arrays of numbers of the structs
+ */
+const TYPED_ARRAYS = {
+    schar: 'Int8Array', int8: 'Int8Array', uchar: 'Uint8Array', uint8: 'Uint8Array', short: 'Int16Array', int16: 'Int16Array',
+    ushort: 'Uint16Array', uint16: 'Uint16Array', char16: 'Uint16Array', int: 'Int32Array', int32: 'Int32Array', uint: 'Uint32Array',
+    uint32: 'Uint32Array', char32: 'Uint32Array', float: 'Float32Array', double: 'Float64Array'
+};
+/**
+ * The name of a parameter in TypeScript: its C name, not a reserved word, not one of the others
+ * @param parameter
+ * @param index
+ * @param taken
+ */
+function parameterName(parameter, index, taken) {
+    let name = parameter.name ?? `arg${index}`;
+    if (RESERVED.has(name))
+        name = `${name}_`;
+    while (taken.has(name))
+        name = `${name}_`;
+    taken.add(name);
+    return name;
+}
+/**
+ * The TypeScript types of C types, as the package converts their values
+ */
+class TypeScriptTypes {
+    #names;
+    /**
+     * Types for the declarations of a library.
+     * @param names The TypeScript names of its structs and unions.
+     */
+    constructor(names) {
+        this.#names = names;
+    }
+    /**
+     * The TypeScript type of a value of a C type.
+     * @param type The C type.
+     * @param flow Whether the value is given to the native code or received from it.
+     */
+    type(type, flow) {
+        switch (type.kind) {
+            case 'primitive':
+                return this.#primitive(type.name, flow);
+            case 'enum':
+                return this.#primitive(type.base, flow);
+            case 'pointer':
+                return this.#pointer(type.to, type.constTarget, flow);
+            case 'array':
+                return this.#array(type.of);
+            case 'struct':
+            case 'union':
+                return this.#names.get(type) ?? this.#inline(type);
+            case 'function':
+                return this.#pointer(type, false, flow);
+        }
+    }
+    /**
+     * The TypeScript type of a function: of a native function, or of a JS callback the native code calls.
+     * @param type The function type.
+     * @param callback Whether it is a JS callback (its arguments received, its result given).
+     */
+    functionType(type, callback = false) {
+        const taken = new Set();
+        const parameters = type.parameters.map((parameter, index) => {
+            return `${parameterName(parameter, index, taken)}: ${callback ? this.type(parameter.type, 'received') : this.#parameter(parameter)}`;
+        });
+        if (type.variadic)
+            parameters.push('...args: unknown[]');
+        return `(${parameters.join(', ')}) => ${this.type(type.result, callback ? 'given' : 'received')}`;
+    }
+    /**
+     * The members of a struct or a union, as the lines of an interface (or of an object type).
+     * @param record The struct or the union.
+     * @param indent The indentation of the lines.
+     */
+    members(record, indent) {
+        return (record.members ?? []).map((member) => `${indent}${member.name}: ${this.type(member.type, 'received')}`);
+    }
+    /**
+     * A parameter of a native function: an output parameter as the array or the object filled
+     * @param parameter
+     */
+    #parameter(parameter) {
+        if (parameter.direction !== 'in' && parameter.type.kind === 'pointer') {
+            const to = parameter.type.to;
+            if ((to.kind === 'struct' || to.kind === 'union') && to.members)
+                return this.type(to, 'received');
+            return `Out<${this.type(to, 'received')}>`;
+        }
+        return this.type(parameter.type, 'given');
+    }
+    #primitive(name, flow) {
+        if (name === 'void')
+            return 'void';
+        if (name === 'bool')
+            return 'boolean';
+        if ((0, Types_js_1.primitiveBig)(name))
+            return flow === 'given' ? 'bigint | number' : 'bigint';
+        return 'number';
+    }
+    #pointer(to, constTarget, flow) {
+        //The strings: char, char16_t, wchar_t
+        if (to.kind === 'primitive' && (to.name === 'char' || to.name === 'char16' || to.name === 'wchar')) {
+            return flow === 'given' && !constTarget ? 'string | Buffer | null' : 'string | null';
+        }
+        if (to.kind === 'function' && flow === 'given')
+            return `(${this.functionType(to, true)}) | Pointer | null`;
+        if (flow !== 'given' || to.kind === 'function')
+            return 'Pointer | null';
+        //A struct or a union given to the function: its object too
+        if ((to.kind === 'struct' || to.kind === 'union') && to.members)
+            return `${this.type(to, 'received')} | Pointer | Buffer | ArrayBufferView | null`;
+        return 'Pointer | Buffer | ArrayBufferView | null';
+    }
+    #array(of) {
+        if (of.kind === 'primitive' || of.kind === 'enum') {
+            const name = of.kind === 'enum' ? of.base : of.name;
+            if (name === 'char' || name === 'wchar')
+                return 'string';
+            if ((0, Types_js_1.primitiveBig)(name))
+                return 'bigint[]';
+            if (name === 'bool')
+                return 'boolean[]';
+            return TYPED_ARRAYS[name] ?? 'number[]';
+        }
+        const element = this.type(of, 'received');
+        return /^[\w.]+$/.test(element) ? `${element}[]` : `Array<${element}>`;
+    }
+    /**
+     * A struct or a union without a name (an anonymous member): an object type
+     * @param record
+     */
+    #inline(record) {
+        if (!record.members)
+            return 'Pointer';
+        return `{${record.members.map((member) => `${member.name}: ${this.type(member.type, 'received')}`).join(', ')}}`;
+    }
+}
+exports.TypeScriptTypes = TypeScriptTypes;

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

@@ -0,0 +1,44 @@
+import type { Pointer } from '../Runtime.js';
+/**
+ * A JS function a library can call at any time (a persistent callback), made by `callback()` of a library: give its
+ * `pointer` to the library, and release it when the library no longer calls it. The callbacks of a library are released
+ * when it is closed; a process has at most 8192 of them at a time.
+ *
+ * When it is called from another thread of the library, it runs in the JS thread once the event loop gets to it. An
+ * exception it throws goes to the error handler of its library (the `error` event of a component), and the library gets
+ * zero (or a null pointer) as its result.
+ * @example
+ * ```typescript
+ * import {loadNativeLibrary, type NativeCallback} from '@lakutata/ffi'
+ *
+ * const vendor = loadNativeLibrary('vendor', 'typedef void (*vendor_log)(int level, const char *message);')
+ * const setLogger = vendor.func<(logger: bigint | null) => void>('void vendor_set_logger(vendor_log logger)')
+ * const logger: NativeCallback = vendor.callback('vendor_log', (level: number, message: string): void => console.log(level, message))
+ * setLogger(logger.pointer)
+ * //Once the library no longer calls it
+ * setLogger(null)
+ * logger.release()
+ * ```
+ */
+export declare class NativeCallback {
+    #private;
+    /**
+     * A registered callback (made by `callback()` of a library, not by this constructor).
+     * @param pointer Its pointer.
+     * @param onRelease Called once it is released.
+     */
+    constructor(pointer: Pointer, onRelease: (callback: NativeCallback) => void);
+    /**
+     * The pointer to give to the library: the address of a C function calling the JS function.
+     */
+    get pointer(): Pointer;
+    /**
+     * Whether it is released: the library must not call it any more.
+     */
+    get released(): boolean;
+    /**
+     * Release it: its pointer is no longer valid, its slot is free for another callback. Releasing it again does
+     * nothing.
+     */
+    release(): void;
+}

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

@@ -0,0 +1,66 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NativeCallback = void 0;
+const koffi_1 = __importDefault(require("koffi"));
+/**
+ * A JS function a library can call at any time (a persistent callback), made by `callback()` of a library: give its
+ * `pointer` to the library, and release it when the library no longer calls it. The callbacks of a library are released
+ * when it is closed; a process has at most 8192 of them at a time.
+ *
+ * When it is called from another thread of the library, it runs in the JS thread once the event loop gets to it. An
+ * exception it throws goes to the error handler of its library (the `error` event of a component), and the library gets
+ * zero (or a null pointer) as its result.
+ * @example
+ * ```typescript
+ * import {loadNativeLibrary, type NativeCallback} from '@lakutata/ffi'
+ *
+ * const vendor = loadNativeLibrary('vendor', 'typedef void (*vendor_log)(int level, const char *message);')
+ * const setLogger = vendor.func<(logger: bigint | null) => void>('void vendor_set_logger(vendor_log logger)')
+ * const logger: NativeCallback = vendor.callback('vendor_log', (level: number, message: string): void => console.log(level, message))
+ * setLogger(logger.pointer)
+ * //Once the library no longer calls it
+ * setLogger(null)
+ * logger.release()
+ * ```
+ */
+class NativeCallback {
+    #pointer;
+    #onRelease;
+    #released = false;
+    /**
+     * A registered callback (made by `callback()` of a library, not by this constructor).
+     * @param pointer Its pointer.
+     * @param onRelease Called once it is released.
+     */
+    constructor(pointer, onRelease) {
+        this.#pointer = pointer;
+        this.#onRelease = onRelease;
+    }
+    /**
+     * The pointer to give to the library: the address of a C function calling the JS function.
+     */
+    get pointer() {
+        return this.#pointer;
+    }
+    /**
+     * Whether it is released: the library must not call it any more.
+     */
+    get released() {
+        return this.#released;
+    }
+    /**
+     * Release it: its pointer is no longer valid, its slot is free for another callback. Releasing it again does
+     * nothing.
+     */
+    release() {
+        if (this.#released)
+            return;
+        this.#released = true;
+        koffi_1.default.unregister(this.#pointer);
+        this.#onRelease(this);
+    }
+}
+exports.NativeCallback = NativeCallback;

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

@@ -0,0 +1,268 @@
+import { type Pointer } from '../Runtime.js';
+import { NativeCallback } from './NativeCallback.js';
+import { type LibraryNames } from './Resolve.js';
+/**
+ * Where a library is found, and how it is closed
+ */
+export interface NativeLibraryOptions {
+    /**
+     * The file of the library: the only one tried when given.
+     */
+    path?: string;
+    /**
+     * The directories tried before the ones of the system, in their order (aliases of the application allowed).
+     */
+    search?: string[];
+    /**
+     * The directory of the libraries of a packaged application, tried after the search directories.
+     */
+    packaged?: string;
+    /**
+     * Whether the library stays loaded once closed (its callbacks are released all the same).
+     * @default false
+     */
+    keepLoaded?: boolean;
+    /**
+     * On Windows, the C library the functions of the library use, whose errno `errno()` reads.
+     * @default 'ucrtbase.dll'
+     */
+    crt?: string;
+    /**
+     * Handles the exceptions thrown by the persistent callbacks (the library gets zero as their result).
+     * @default writes them to the console
+     */
+    onCallbackError?: (error: unknown) => void;
+    /**
+     * The worker threads of the library, which run its asynchronous functions: 0 for the thread pool of the runtime
+     * (the one of libuv in Node.js, shared with the file system); with one thread, the asynchronous calls run one after
+     * the other, in their order (a library that is not thread-safe). The synchronous functions run in the thread
+     * calling them.
+     * @default 0
+     */
+    threads?: number;
+}
+/**
+ * How a function is bound
+ */
+export interface NativeFunctionOptions {
+    /**
+     * Whether it runs in another thread, returning a promise: for the functions that block. It runs in the threads of
+     * the library when it has some (`threads`), else in the thread pool of the runtime (Node.js runs them in the pool
+     * of libuv, 4 threads by default, shared with the file system: raise UV_THREADPOOL_SIZE for many of them), where a
+     * variadic function cannot be asynchronous.
+     * @default false
+     */
+    async?: boolean;
+    /**
+     * Frees the strings the function gives (its result, its output strings) once read: the name of the function of the
+     * library that frees them (`sqlite3_free`), or true for free() of the C library. On Windows, a library built with
+     * another C library must be given its own function.
+     */
+    free?: string | boolean;
+    /**
+     * Its 64-bit integers (its result, its output integers) as numbers rather than bigints: a RangeError when one is not
+     * a safe integer.
+     * @default 'bigint'
+     */
+    int64?: 'bigint' | 'number';
+}
+/**
+ * A variable a library exports
+ */
+export interface NativeVariableAccessor<T = unknown> {
+    /**
+     * Its address.
+     */
+    readonly address: Pointer;
+    /**
+     * Its value (an array of char of unknown length is read as a string).
+     */
+    get(): T;
+    /**
+     * Change its value.
+     * @param value The value.
+     * @throws {NativeDeclarationException} When it is const.
+     */
+    set(value: T): void;
+}
+/**
+ * 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()
+ * ```
+ */
+export declare class NativeLibraryHandle {
+    #private;
+    /**
+     * 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: LibraryNames, declarations?: string, options?: NativeLibraryOptions);
+    /**
+     * The file the library was loaded from.
+     */
+    get file(): string;
+    /**
+     * Whether it is closed.
+     */
+    get closed(): boolean;
+    /**
+     * The asynchronous calls running.
+     */
+    get pending(): number;
+    /**
+     * The worker threads of the library (0: the asynchronous calls run in the thread pool of the runtime).
+     */
+    get threads(): number;
+    /**
+     * 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(): Promise<void>;
+    /**
+     * 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(): Readonly<Record<string, bigint>>;
+    /**
+     * 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: string): void;
+    /**
+     * 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<T extends (...args: any[]) => any = (...args: any[]) => any>(prototype: string, options?: NativeFunctionOptions): T;
+    /**
+     * 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<T extends (...args: any[]) => any = (...args: any[]) => any>(name: string, options?: NativeFunctionOptions): T;
+    /**
+     * 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<T = unknown>(declaration: string): NativeVariableAccessor<T>;
+    /**
+     * 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: string, callback: (...args: any[]) => any): NativeCallback;
+    /**
+     * 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<T = unknown>(pointer: Pointer, type: string, count?: number): T;
+    /**
+     * 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: Pointer, type: string, value: unknown): void;
+    /**
+     * The size of a type of the declarations, in bytes.
+     * @param type The type.
+     */
+    sizeOf(type: string): number;
+    /**
+     * The offset of a member of a struct of the declarations, in bytes.
+     * @param type The struct.
+     * @param member The member.
+     */
+    offsetOf(type: string, member: string): number;
+    /**
+     * 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: string, count?: number): Pointer;
+    /**
+     * Free memory allocated by `alloc()`.
+     * @param pointer Its address.
+     */
+    free(pointer: Pointer): void;
+    /**
+     * 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(): number;
+    /**
+     * 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(): number | undefined;
+    /**
+     * 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?: number): Promise<boolean>;
+    /**
+     * 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.
+     */
+    close(timeout?: number): Promise<void>;
+}
+/**
+ * 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()
+ * ```
+ */
+export declare function loadNativeLibrary(names: LibraryNames, declarations?: string, options?: NativeLibraryOptions): NativeLibraryHandle;