@lakutata/ffi 0.0.0-stage → 3.1.2

package/LICENSE

@@ -0,0 +1,23 @@
+MIT License
+
+Copyright (c) 2023-present Lakutata
+
+All rights reserved
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,164 @@
-# Temporary Holding Version
+# @lakutata/ffi
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+English | [中文](README.zh-CN.md)
+
+Native libraries for the [lakutata](https://github.com/lakutata/lakutata) framework: the C functions of `.so`, `.dylib`
+and `.dll` files called from Node.js, the main process of Electron and Bun, without compiling anything. A library is
+declared with the C declarations of its headers (structs, unions, enums, typedefs, pointers to functions, prototypes,
+`#define`), and each library is a component of the application. It is built on [koffi](https://koffi.dev/). The
+`lakutata` package does not re-export this package: import it from `@lakutata/ffi`.
+
+## Installation
+
+```shell
+npm install lakutata @lakutata/ffi
+```
+
+- koffi comes with a package of prebuilt binaries for each platform, installed with it; npm may warn that its install
+  script was not run: it is not needed.
+- Node.js `^22.13.0 || >=24.11.0`, the main process of Electron, or Bun. Its peer dependency `@lakutata/core` is
+  installed with `lakutata`.
+
+## Usage
+
+### A library
+
+A subclass of `NativeLibrary`: `@Library` gives its file names (one by platform, or one completed as each platform names
+libraries) and its declarations, `@Native` binds a function to a property, `@NativeVariable` a variable.
+
+```typescript
+import {Application} from 'lakutata'
+import {buildNativeLibraryOptions, Library, Native, NativeLibrary, NativeVariable, 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
+        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
+
+    //Runs in a thread of the pool; the error message it gives is freed by sqlite3_free
+    @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>
+
+    //The function of the declarations named as the property
+    @Native()
+    public readonly sqlite3_close: (db: Pointer) => number
+
+    @NativeVariable('extern const char sqlite3_version[]')
+    public readonly version: string
+}
+
+Application
+    .run(() => ({
+        id: 'store.app',
+        name: 'Store',
+        components: {
+            sqlite: buildNativeLibraryOptions(SQLite)
+        }
+    }))
+    .onLaunched(async (app: Application): Promise<void> => {
+        const sqlite: SQLite = await app.getObject('sqlite')
+        const db: Out<Pointer> = [null]
+        if (sqlite.open(':memory:', db) !== Number(sqlite.constants.SQLITE_OK)) throw new Error('open failed')
+        const error: Out<string> = [null]
+        if (await sqlite.exec(db[0]!, 'CREATE TABLE t (id INTEGER)', null, null, error)) console.error(error[0])
+        sqlite.sqlite3_close(db[0]!)
+        console.log(sqlite.version)
+    })
+```
+
+- **Where it is found**: the `path` of the configuration (alone, when given), the directories of `search` in the
+  configuration and in `@Library`, the directory `native` of the resources of a packaged application, then where the
+  system looks for libraries. `c` is the C library on each system (musl included), `m` its mathematical functions.
+- **The values**: numbers; strings for `char *`; bigints for pointers and for every 64-bit integer (`size_t`, `long`,
+  `int64_t`…), or numbers with `{int64: 'number'}`; objects for structs and unions, their bitfields by their names; an
+  array of one element for an `_Out_` integer or pointer (`Out<T>`).
+- **Callbacks**: a JS function given for a pointer to a function is valid during the call; `callback(type, fn)` makes
+  one the library keeps, whose exceptions are `error` events of the component.
+- **Threads**: the asynchronous functions run in the thread pool of the runtime, or in worker threads of the library
+  when `threads` is given on `@Library` (or in the configuration). With `threads: 1`, they run one after the other,
+  for a library that is not thread-safe; with several, each call goes to the least busy thread. A variadic function can
+  be asynchronous there.
+- **Destroyed** with the application: its properties throw, the asynchronous calls running are awaited, its callbacks
+  released, the library unloaded. Calls still running after `drainTimeout` keep the library loaded, with its callbacks
+  and its memory, since a native call cannot be interrupted.
+
+### Without the container
+
+```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)')
+const snprintf = libc.func<(buffer: Buffer, size: number, format: string, ...args: unknown[]) => number>('int snprintf(char *buffer, size_t size, const char *format, ...)')
+console.log(div(17, 5))
+//The types of the extra arguments of a variadic function, by their C names
+const buffer: Buffer = Buffer.alloc(32)
+snprintf(buffer, buffer.length, '%s=%d', 'const char *', 'count', 'int', 42)
+await libc.close()
+```
+
+### Generating the class from the header
+
+For a library with many functions, the class is generated from its header by the command line tool of lakutata
+(`@lakutata/cli`), or by `generateNativeLibrary()` of `@lakutata/ffi/generator`:
+
+```shell
+lakutata ffi generate /usr/include/sqlite3.h --class-name SQLite3 --out src/native/SQLite3.ts
+```
+
+The header is run through the preprocessor of the C compiler, the declarations of the library are kept, and the
+functions the library cannot give are left out and listed. Then mark the output parameters `_Out_` and the functions
+that block `{async: true}` in the file generated, as the guide shows: a header does not say which ones they are.
+
+### Packaging
+
+The bundles, the executables and the installers of Electron made by `lakutata package` carry koffi and its binary for
+the platform. A library shipped with the application goes in the resources, in `native`
+(`"lakutata": {"resources": [{"from": "vendor/lib", "to": "native"}]}` in the package.json). On Alpine, make the
+executables with Bun (`--runtime bun`).
+
+## API
+
+| Export | What it is |
+|---|---|
+| `NativeLibrary` | The component of a library: its functions and variables on its properties; `func`, `variable`, `callback`, `read`, `write`, `sizeOf`, `offsetOf`, `alloc`, `free`, `errno`, `windowsError`, `constants`, `file`, `pending`, `threadCount`; the `error` event of its callbacks |
+| `buildNativeLibraryOptions`, `NativeLibraryConfig` | Its declaration in the components, and its options: `path`, `search`, `keepLoaded`, `drainTimeout`, `threads` |
+| `Library`, `LibraryOptions` | Class decorator: the library of a `NativeLibrary` subclass: `names`, `search`, `declarations`, `crt`, `threads` |
+| `Native` | Property decorator: a function (a prototype, a declared name, or the name of the property) and its options: `async`, `free`, `int64` |
+| `NativeVariable` | Property decorator: a variable the library exports |
+| `loadNativeLibrary`, `NativeLibraryHandle`, `NativeLibraryOptions` | A library without the container: `func`, `function`, `variable`, `callback`, `declare`, `read`, `write`, `sizeOf`, `offsetOf`, `alloc`, `free`, `errno`, `windowsError`, `threads`, `ready`, `drain`, `close` |
+| `NativeFunctionOptions`, `NativeVariableAccessor`, `NativeCallback`, `LibraryNames`, `Pointer`, `Out` | The options of a function, a variable, a persistent callback (`pointer`, `release()`), the names of a library, a pointer (a bigint), an output parameter |
+| `readCString`, `readWString`, `readBuffer`, `viewBuffer`, `readValue`, `readArray`, `writeValue`, `allocMemory`, `freeMemory`, `sizeOf` | Native memory, with the built-in types (`viewBuffer` does not copy; Electron refuses it) |
+| `lastErrno`, `lastWindowsError` | The errno of the last call (on Windows, the one of the C library given), the error of the Windows API |
+| `generateNativeLibrary`, `defaultCompiler` (`@lakutata/ffi/generator`) | The class of a library generated from its header (its code, its declarations, what was left out), the C compiler run by default |
+
+The typings document every declaration, with examples.
+
+## Errors
+
+| Error | When |
+|---|---|
+| `NativeDeclarationException` | Declarations or a prototype cannot be read (with their line and column: a type not declared, `#if`, a macro with arguments, `long double`…), a function is not in the library, a `va_list` is passed, a class has no `@Library` |
+| `NativeLibraryNotFoundException` | The library cannot be loaded: its message lists each file tried and why |
+| `NativeLibraryClosedException` | A function, a variable or a callback of a closed library is used; a call still running in the threads of a library when it is closed |
+| `NativeMemoryException` | A null pointer or a negative length is given to the memory functions, `viewBuffer` in Electron |
+| `TypeError` (from koffi) | An argument of the wrong type |
+| `RangeError` | A 64-bit integer that is not a safe integer, for a function declared with `{int64: 'number'}` |
+
+A C function called with a wrong prototype, or given a wrong pointer, ends the process: no exception can catch it.
+
+## See also
+
+- The guide on the website: [FFI](https://lakutata.com/guide/FFI).
+- `doc/en/FFI.md` in the `lakutata` package (Chinese version in `doc/zh`): the guide to native libraries.
+- `doc/en/NativeAddons.md` in the `lakutata` package: native addons written in C++ or Rust, for what a library of C
+  functions cannot give.
+- [koffi](https://koffi.dev/): the FFI the package is built on.
+- `@lakutata/core` (`lakutata`): components, `Application` and dependency injection.

package/README.zh-CN.md

@@ -0,0 +1,140 @@
+# @lakutata/ffi
+
+[English](README.md) | 中文
+
+[lakutata](https://github.com/lakutata/lakutata) 框架的动态库调用：在 Node.js、Electron 的主进程和 Bun 里调用 `.so`、`.dylib`、`.dll` 文件中的 C 函数，不需要编译任何东西。库用它头文件里的 C 声明来描述（结构体、联合、枚举、typedef、函数指针、原型、`#define`），每个库都是应用的一个组件。它基于 [koffi](https://koffi.dev/)。`lakutata` 包不重新导出这个包：请从 `@lakutata/ffi` 导入。
+
+## 安装
+
+```shell
+npm install lakutata @lakutata/ffi
+```
+
+- koffi 会连同各平台的预编译文件一起安装（每个平台一个包）；npm 可能会提示它的安装脚本没有运行：不需要运行它。
+- 需要 Node.js `^22.13.0 || >=24.11.0`、Electron 的主进程或 Bun。它的 peer 依赖 `@lakutata/core` 会随 `lakutata` 一起安装。
+
+## 用法
+
+### 一个库
+
+一个库就是 `NativeLibrary` 的一个子类：`@Library` 给出它的文件名（可以按平台分别写，也可以写一个名字，按各平台给库命名的方式补全）和它的声明，`@Native` 把一个函数绑到一个属性上，`@NativeVariable` 绑定一个变量。
+
+```typescript
+import {Application} from 'lakutata'
+import {buildNativeLibraryOptions, Library, Native, NativeLibrary, NativeVariable, 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
+        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
+
+    //在线程池里执行；它给出的错误信息由 sqlite3_free 释放
+    @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>
+
+    //声明里和属性同名的函数
+    @Native()
+    public readonly sqlite3_close: (db: Pointer) => number
+
+    @NativeVariable('extern const char sqlite3_version[]')
+    public readonly version: string
+}
+
+Application
+    .run(() => ({
+        id: 'store.app',
+        name: 'Store',
+        components: {
+            sqlite: buildNativeLibraryOptions(SQLite)
+        }
+    }))
+    .onLaunched(async (app: Application): Promise<void> => {
+        const sqlite: SQLite = await app.getObject('sqlite')
+        const db: Out<Pointer> = [null]
+        if (sqlite.open(':memory:', db) !== Number(sqlite.constants.SQLITE_OK)) throw new Error('open failed')
+        const error: Out<string> = [null]
+        if (await sqlite.exec(db[0]!, 'CREATE TABLE t (id INTEGER)', null, null, error)) console.error(error[0])
+        sqlite.sqlite3_close(db[0]!)
+        console.log(sqlite.version)
+    })
+```
+
+- **到哪里找库**：配置里的 `path`（给了就只试它），配置和 `@Library` 里 `search` 的目录，打包后应用的资源目录下的 `native` 目录，最后是系统找库的位置。`c` 表示各系统上的 C 标准库（包括 musl），`m` 表示它的数学函数。
+- **值的对应关系**：数字对应 number；`char *` 对应字符串；指针和所有 64 位整数（`size_t`、`long`、`int64_t` 等）对应 bigint，声明时加上 `{int64: 'number'}` 就改为 number；结构体和联合对应对象，位域按名字读写；`_Out_` 的整数或指针用只有一个元素的数组传入（`Out<T>`）。
+- **回调**：给函数指针参数传入的 JS 函数只在这次调用期间有效；`callback(type, fn)` 生成一个库可以保存起来以后再调用的回调，它抛出的异常会成为组件的 `error` 事件。
+- **线程**：异步函数默认在运行时的线程池里执行；在 `@Library`（或配置）里设置 `threads` 后，改在库自己的线程里执行。`threads: 1` 时，异步调用一个接一个执行，适合不是线程安全的库；有多个线程时，每个调用交给最空闲的线程。在这些线程里，可变参数的函数也可以异步调用。
+- **销毁**：随应用一起销毁时，属性开始抛出异常，会等进行中的异步调用结束，回调全部释放，库被卸载。原生调用没法中途打断：过了 `drainTimeout` 还有调用没结束时，库连同它的回调和内存都保留下来。
+
+### 不用容器
+
+```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)')
+const snprintf = libc.func<(buffer: Buffer, size: number, format: string, ...args: unknown[]) => number>('int snprintf(char *buffer, size_t size, const char *format, ...)')
+console.log(div(17, 5))
+//可变参数函数的额外参数，前面用 C 类型名写出类型
+const buffer: Buffer = Buffer.alloc(32)
+snprintf(buffer, buffer.length, '%s=%d', 'const char *', 'count', 'int', 42)
+await libc.close()
+```
+
+### 根据头文件生成类
+
+函数很多的库，可以用 lakutata 的命令行工具（`@lakutata/cli`）或 `@lakutata/ffi/generator` 的 `generateNativeLibrary()` 根据头文件生成类：
+
+```shell
+lakutata ffi generate /usr/include/sqlite3.h --class-name SQLite3 --out src/native/SQLite3.ts
+```
+
+头文件先经过 C 编译器的预处理器，保留库自己的声明，库给不了的函数会被去掉并列出来。之后请在生成的文件里把输出参数标成 `_Out_`，把会阻塞的函数声明为 `{async: true}`，做法见指南：头文件看不出是哪些。
+
+### 打包
+
+`lakutata package` 打出的 bundle、可执行文件和 Electron 安装包都会带上 koffi 和本平台的预编译文件。要和应用一起发布的库放进资源里的 `native` 目录（在 package.json 里写 `"lakutata": {"resources": [{"from": "vendor/lib", "to": "native"}]}`）。在 Alpine 上请用 Bun 打可执行文件（`--runtime bun`）。
+
+## API
+
+| 导出 | 是什么 |
+|---|---|
+| `NativeLibrary` | 库的组件：函数和变量在它的属性上；`func`、`variable`、`callback`、`read`、`write`、`sizeOf`、`offsetOf`、`alloc`、`free`、`errno`、`windowsError`、`constants`、`file`、`pending`、`threadCount`；回调异常的 `error` 事件 |
+| `buildNativeLibraryOptions`、`NativeLibraryConfig` | 在 `components` 里注册它，以及它的选项：`path`、`search`、`keepLoaded`、`drainTimeout`、`threads` |
+| `Library`、`LibraryOptions` | 类装饰器：`NativeLibrary` 子类的库：`names`、`search`、`declarations`、`crt`、`threads` |
+| `Native` | 属性装饰器：一个函数（原型、声明里的名字，或者属性名）及其选项：`async`、`free`、`int64` |
+| `NativeVariable` | 属性装饰器：库导出的一个变量 |
+| `loadNativeLibrary`、`NativeLibraryHandle`、`NativeLibraryOptions` | 不用容器时的库：`func`、`function`、`variable`、`callback`、`declare`、`read`、`write`、`sizeOf`、`offsetOf`、`alloc`、`free`、`errno`、`windowsError`、`threads`、`ready`、`drain`、`close` |
+| `NativeFunctionOptions`、`NativeVariableAccessor`、`NativeCallback`、`LibraryNames`、`Pointer`、`Out` | 函数的选项、变量、持久回调（`pointer`、`release()`）、库的文件名、指针（bigint）、输出参数 |
+| `readCString`、`readWString`、`readBuffer`、`viewBuffer`、`readValue`、`readArray`、`writeValue`、`allocMemory`、`freeMemory`、`sizeOf` | 用内置类型读写原生内存（`viewBuffer` 不复制；Electron 里不能用） |
+| `lastErrno`、`lastWindowsError` | 上一次调用后的 errno（Windows 上是指定的 C 运行库的 errno），以及 Windows API 的错误 |
+| `generateNativeLibrary`、`defaultCompiler`（`@lakutata/ffi/generator`） | 根据头文件生成库的类（它的代码、声明，以及去掉了哪些），以及默认运行的 C 编译器 |
+
+类型声明里有每个导出的说明和示例。
+
+## 错误
+
+| 错误 | 什么时候 |
+|---|---|
+| `NativeDeclarationException` | 声明或原型读不了（带行号和列号：类型没有声明、`#if`、带参数的宏、`long double` 等）、库里没有这个函数、传了 `va_list`、类上没有 `@Library` |
+| `NativeLibraryNotFoundException` | 库加载不了：消息里列出试过的每个文件和原因 |
+| `NativeLibraryClosedException` | 库关闭后又使用它的函数、变量或回调；库关闭时，它的线程里还没结束的调用 |
+| `NativeMemoryException` | 给内存函数传了空指针或负的长度、在 Electron 里用 `viewBuffer` |
+| `TypeError`（来自 koffi） | 参数类型不对 |
+| `RangeError` | 声明了 `{int64: 'number'}` 的函数遇到超出安全整数范围的 64 位整数 |
+
+C 函数的原型写错，或者传了错误的指针，整个进程都会退出，任何异常处理都拦不住。
+
+## 另见
+
+- 网站上的指南：[FFI](https://lakutata.com/zh/guide/FFI)。
+- `lakutata` 包里的 `doc/zh/FFI.md`（英文版在 `doc/en`）：动态库调用指南。
+- `lakutata` 包里的 `doc/zh/NativeAddons.md`：用 C++ 或 Rust 编写的原生插件，用于 C 函数库做不到的情况。
+- [koffi](https://koffi.dev/)：这个包所基于的 FFI。
+- `@lakutata/core`（`lakutata`）：组件、`Application` 和依赖注入。

package/dist/cjs/components/NativeLibrary.d.ts

@@ -0,0 +1,229 @@
+import { Component, type ComponentOptions } from '@lakutata/core';
+import type { NativeCallback } from '../lib/library/NativeCallback.js';
+import { type NativeFunctionOptions, type NativeVariableAccessor } from '../lib/library/NativeLibraryHandle.js';
+import type { Pointer } from '../lib/Runtime.js';
+/**
+ * The options of a library in the configuration (see {@link buildNativeLibraryOptions}): where it is found, how it is
+ * closed
+ */
+export interface NativeLibraryConfig {
+    /**
+     * The file of the library: the only one tried when given (an alias of the application can start it).
+     */
+    path?: string;
+    /**
+     * Directories tried before the ones of `@Library`, in their order.
+     */
+    search?: string[];
+    /**
+     * Whether the library stays loaded once the component is destroyed.
+     * @default false
+     */
+    keepLoaded?: boolean;
+    /**
+     * How long the destruction waits for the asynchronous calls running, in milliseconds. Calls still running then
+     * keep the library loaded, with its callbacks and its memory (a native call cannot be interrupted).
+     * @default 10000
+     */
+    drainTimeout?: number;
+    /**
+     * The worker threads that run the asynchronous functions of the library, replacing the number of `@Library`: 0 for
+     * the thread pool of the runtime; 1 runs them one after the other.
+     */
+    threads?: number;
+}
+/**
+ * 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 declare class NativeLibrary extends Component {
+    #private;
+    /**
+     * The file of the library: the only one tried when given.
+     */
+    protected readonly path?: string;
+    /**
+     * Directories tried before the ones of `@Library`.
+     */
+    protected readonly search?: string[];
+    /**
+     * Whether the library stays loaded once the component is destroyed.
+     */
+    protected readonly keepLoaded?: boolean;
+    /**
+     * How long the destruction waits for the asynchronous calls running, in milliseconds.
+     */
+    protected readonly drainTimeout?: number;
+    /**
+     * The worker threads that run the asynchronous functions of the library.
+     */
+    protected readonly threads?: number;
+    /**
+     * Load the library and bind its functions and variables to their properties.
+     * @protected
+     */
+    protected init(): Promise<void>;
+    /**
+     * 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
+     */
+    protected destroy(): Promise<void>;
+    /**
+     * The file the library was loaded from.
+     */
+    get file(): string;
+    /**
+     * The asynchronous calls running.
+     */
+    get pending(): number;
+    /**
+     * The worker threads of the library (0: its asynchronous calls run in the thread pool of the runtime).
+     */
+    get threadCount(): number;
+    /**
+     * 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(): Readonly<Record<string, bigint>>;
+    /**
+     * 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<T extends (...args: any[]) => any = (...args: any[]) => any>(prototype: string, options?: NativeFunctionOptions): T;
+    /**
+     * 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<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
+     * 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: 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, 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: 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 of `@Library`, ucrtbase.dll by
+     * default); with threads, the one of the thread of the last asynchronous call completed.
+     */
+    errno(): number;
+    /**
+     * 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(): number | undefined;
+}
+/**
+ * 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 declare function buildNativeLibraryOptions(library: typeof NativeLibrary, options?: NativeLibraryConfig): ComponentOptions<NativeLibraryConfig>;