@lakutata/ffi 0.0.0-stage → 3.1.2

package/dist/types/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;

package/dist/types/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;
+};

package/dist/types/lib/thread/NativeThreads.d.ts

@@ -0,0 +1,80 @@
+import type { FunctionDeclaration } from '../declarations/Types.js';
+import type { ThreadFunctionOptions } from './ThreadProtocol.js';
+/**
+ * A function called in the threads: how a thread binds it
+ */
+export interface ThreadFunction {
+    /**
+     * Its prototype, or the name of a declared function
+     */
+    readonly declaration: string;
+    readonly named: boolean;
+    readonly options: ThreadFunctionOptions;
+    /**
+     * Its declaration, read by the thread of the library: which arguments are written by the function, which are
+     * callbacks
+     */
+    readonly type: FunctionDeclaration;
+}
+/**
+ * The result of a call in a thread: its value, and the errno of the thread after it
+ */
+export interface ThreadResult {
+    readonly value: unknown;
+    readonly errno: number;
+    readonly windowsError?: number;
+}
+/**
+ * The worker threads of a library: they load it, and run its asynchronous calls (synchronously, each in its thread);
+ * with one thread, in the order they are made. The arguments are copied to the thread and the ones the function writes
+ * copied back; a JS function given as a callback is registered for the call in the thread of the library, which runs it
+ * when the library calls it
+ */
+export declare class NativeThreads {
+    #private;
+    /**
+     * Start the threads of a library.
+     * @param file The file of the library, as loaded by this thread.
+     * @param declarations Its C declarations.
+     * @param count The number of threads.
+     * @param crt On Windows, the C library whose errno is read after each call.
+     */
+    constructor(file: string, declarations: string, count: number, crt?: string);
+    /**
+     * Settled once every thread has loaded the library: rejected with the error of a thread that could not.
+     */
+    get ready(): Promise<void>;
+    /**
+     * The number of threads.
+     */
+    get count(): number;
+    /**
+     * Add declarations to the ones of the threads (and of the threads started later).
+     * @param declarations The declarations.
+     */
+    declare(declarations: string): void;
+    /**
+     * Bind a function in the threads now rather than at its first call: when the library is made, while the threads
+     * start (a thread started later binds it at its first call in it).
+     * @param fn The function.
+     */
+    bind(fn: ThreadFunction): void;
+    /**
+     * Call a function in the least busy thread (with one thread, after the calls made before).
+     * @param fn The function.
+     * @param args Its arguments.
+     * @returns Its value and the errno of the thread after it.
+     */
+    call(fn: ThreadFunction, args: unknown[]): Promise<ThreadResult>;
+    /**
+     * Stop a thread as if it had ended on its own (for the tests): its calls fail, the next call starts a new one.
+     * @param index The index of the thread.
+     */
+    stopThread(index: number): Promise<void>;
+    /**
+     * Close the threads: each unloads the library and ends; the ones still running after a while are stopped. A thread
+     * still running a call (its native code did not return) is stopped at once, the call rejected: the thread ends
+     * once the native code returns.
+     */
+    close(): Promise<void>;
+}

package/dist/types/lib/thread/NativeWorker.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Serve the calls of a library in this worker thread: it loads the library, binds the functions it is asked to bind
+ * (synchronous: the thread is the one waiting), calls them in the order of the messages, and sends back their results,
+ * the arguments asked back (the output parameters, the buffers written) and its errno after each call
+ */
+export declare function runNativeWorker(): void;

package/dist/types/lib/thread/NativeWorkerCode.d.ts

@@ -0,0 +1,5 @@
+/**
+ * The code of the worker threads of the libraries: NativeWorker and what it uses bundled into one script, written by the
+ * build (scripts/worker.mjs) in place of this empty one
+ */
+export declare const nativeWorkerCode: string;

package/dist/types/lib/thread/PackageRequire.d.ts

@@ -0,0 +1,6 @@
+/**
+ * The require of the package (createRequire(import.meta.url) in the ES modules, require in CommonJS), written by the
+ * build (scripts/worker.mjs) in place of this one: it resolves koffi for the worker threads, from the package (in a
+ * packed application, from its native tree)
+ */
+export declare const packageRequire: NodeJS.Require | undefined;

package/dist/types/lib/thread/ThreadProtocol.d.ts

@@ -0,0 +1,77 @@
+/**
+ * What a worker thread of a library is started with
+ */
+export interface NativeWorkerData {
+    /**
+     * The path of koffi, resolved by the thread of the library
+     */
+    readonly koffi: string;
+    /**
+     * The file of the library, as the thread of the library loaded it
+     */
+    readonly file: string;
+    /**
+     * The C declarations of the library
+     */
+    readonly declarations: string;
+    /**
+     * On Windows, the C library whose errno is read after each call
+     */
+    readonly crt?: string;
+}
+/**
+ * The options a function is bound with in a thread (the synchronous ones: the thread calls it synchronously)
+ */
+export interface ThreadFunctionOptions {
+    readonly free?: string | boolean;
+    readonly int64?: 'bigint' | 'number';
+}
+/**
+ * An error sent from a thread: made again by its name
+ */
+export interface ThreadError {
+    readonly name: string;
+    readonly message: string;
+}
+/**
+ * The messages to a thread: a function bound (a prototype, or the name of a declared function), declarations added, a
+ * call (the arguments to send back after it), the end
+ */
+export type ToNativeWorker = {
+    readonly type: 'bind';
+    readonly id: number;
+    readonly declaration: string;
+    readonly named: boolean;
+    readonly options: ThreadFunctionOptions;
+} | {
+    readonly type: 'declare';
+    readonly declarations: string;
+} | {
+    readonly type: 'call';
+    readonly id: number;
+    readonly function: number;
+    readonly args: unknown[];
+    readonly back: readonly number[];
+} | {
+    readonly type: 'close';
+};
+/**
+ * The messages from a thread: the library loaded (or not), the result of a call (its value or its error, the arguments
+ * asked back, the errno of the thread after it), the end
+ */
+export type FromNativeWorker = {
+    readonly type: 'ready';
+} | {
+    readonly type: 'failed';
+    readonly error: ThreadError;
+} | {
+    readonly type: 'result';
+    readonly id: number;
+    readonly value?: unknown;
+    readonly error?: ThreadError;
+    readonly back: readonly unknown[];
+    readonly errno: number;
+    readonly windowsError?: number;
+} | {
+    readonly type: 'closed';
+};

package/package.json

@@ -1,6 +1,87 @@
 {
   "name": "@lakutata/ffi",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "3.1.2",
+  "description": "Native libraries for the lakutata framework: C functions of .so, .dylib and .dll files called from Node.js, Electron and Bun, declared with the C declarations of their headers, a library being a component of the application.",
+  "keywords": [
+    "lakutata",
+    "ffi",
+    "native",
+    "c",
+    "dll",
+    "shared-library",
+    "dlopen",
+    "koffi",
+    "bindings",
+    "typescript"
+  ],
+  "homepage": "https://lakutata.com/packages/ffi",
+  "bugs": {
+    "url": "https://github.com/lakutata/lakutata/issues",
+    "email": "admin@lakutata.com"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/lakutata/lakutata.git",
+    "directory": "packages/ffi"
+  },
+  "author": "alex.ma",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/cjs/exports/FFI.js",
+  "types": "./dist/cjs/exports/FFI.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/types/exports/FFI.d.ts",
+        "default": "./dist/esm/exports/FFI.js"
+      },
+      "require": {
+        "types": "./dist/cjs/exports/FFI.d.ts",
+        "default": "./dist/cjs/exports/FFI.js"
+      }
+    },
+    "./generator": {
+      "import": {
+        "types": "./dist/types/exports/Generator.d.ts",
+        "default": "./dist/esm/exports/Generator.js"
+      },
+      "require": {
+        "types": "./dist/cjs/exports/Generator.d.ts",
+        "default": "./dist/cjs/exports/Generator.js"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "clean": "node -e \"require('node:fs').rmSync('dist', {recursive: true, force: true})\"",
+    "build:cjs": "tsc -p tsconfig.cjs.json",
+    "build:esm": "tsc -p tsconfig.esm.json",
+    "build:cjs-pkg": "node ../../scripts/package-build/cjs-package.mjs",
+    "build:js": "npm run build:cjs && npm run build:esm && npm run build:cjs-pkg && npm run build:worker",
+    "rebuild": "npm run clean && npm run build:js",
+    "compile": "npm run rebuild",
+    "test:unit": "npm run compile && node --test --test-timeout=60000 \"dist/esm/tests/**/*.spec.js\"",
+    "test:bun": "sh test-env/bun.sh",
+    "test:electron": "electron test-env/electron/main.mjs",
+    "build:worker": "node scripts/worker.mjs"
+  },
+  "engines": {
+    "node": "^22.13.0 || >=24.11.0"
+  },
+  "files": [
+    "dist",
+    "!dist/*/tests",
+    "*.md",
+    "LICENSE",
+    "package.json"
+  ],
+  "peerDependencies": {
+    "@lakutata/core": "~3.1.1"
+  },
+  "dependencies": {
+    "koffi": "3.3.4"
+  },
+  "devDependencies": {
+    "esbuild": "^0.28.2"
+  }
+}