@lakutata/ffi 0.0.0-stage → 3.1.5

package/dist/cjs/exceptions/NativeLibraryNotFoundException.d.ts

@@ -0,0 +1,11 @@
+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 declare class NativeLibraryNotFoundException extends Exception {
+    /**
+     * `'E_NATIVE_LIBRARY_NOT_FOUND'`.
+     */
+    errno: string | number;
+}

package/dist/cjs/exceptions/NativeLibraryNotFoundException.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NativeLibraryNotFoundException = void 0;
+const core_1 = require("@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'`.
+ */
+class NativeLibraryNotFoundException extends core_1.Exception {
+    constructor() {
+        super(...arguments);
+        /**
+         * `'E_NATIVE_LIBRARY_NOT_FOUND'`.
+         */
+        this.errno = 'E_NATIVE_LIBRARY_NOT_FOUND';
+    }
+}
+exports.NativeLibraryNotFoundException = NativeLibraryNotFoundException;

package/dist/cjs/exceptions/NativeMemoryException.d.ts

@@ -0,0 +1,11 @@
+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 declare class NativeMemoryException extends Exception {
+    /**
+     * `'E_NATIVE_MEMORY'`.
+     */
+    errno: string | number;
+}

package/dist/cjs/exceptions/NativeMemoryException.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NativeMemoryException = void 0;
+const core_1 = require("@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'`.
+ */
+class NativeMemoryException extends core_1.Exception {
+    constructor() {
+        super(...arguments);
+        /**
+         * `'E_NATIVE_MEMORY'`.
+         */
+        this.errno = 'E_NATIVE_MEMORY';
+    }
+}
+exports.NativeMemoryException = NativeMemoryException;

package/dist/cjs/exports/FFI.d.ts

@@ -0,0 +1,12 @@
+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 { type Pointer } from '../lib/Runtime.js';
+export { type LibraryNames } from '../lib/library/Resolve.js';
+export { NativeCallback } from '../lib/library/NativeCallback.js';
+export { loadNativeLibrary, NativeLibraryHandle, type NativeFunctionOptions, type NativeLibraryOptions, type NativeVariableAccessor } from '../lib/library/NativeLibraryHandle.js';
+export { allocMemory, freeMemory, lastErrno, lastWindowsError, type Out, readArray, readBuffer, readCString, readValue, readWString, sizeOf, viewBuffer, writeValue } from '../lib/Memory.js';
+export { Library, type LibraryOptions } from '../decorators/Library.js';
+export { Native, NativeVariable } from '../decorators/Native.js';
+export { buildNativeLibraryOptions, NativeLibrary, type NativeLibraryConfig } from '../components/NativeLibrary.js';

package/dist/cjs/exports/FFI.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NativeLibrary = exports.buildNativeLibraryOptions = exports.NativeVariable = exports.Native = exports.Library = exports.writeValue = exports.viewBuffer = exports.sizeOf = exports.readWString = exports.readValue = exports.readCString = exports.readBuffer = exports.readArray = exports.lastWindowsError = exports.lastErrno = exports.freeMemory = exports.allocMemory = exports.NativeLibraryHandle = exports.loadNativeLibrary = exports.NativeCallback = exports.NativeMemoryException = exports.NativeLibraryClosedException = exports.NativeLibraryNotFoundException = exports.NativeDeclarationException = void 0;
+var NativeDeclarationException_js_1 = require("../exceptions/NativeDeclarationException.js");
+Object.defineProperty(exports, "NativeDeclarationException", { enumerable: true, get: function () { return NativeDeclarationException_js_1.NativeDeclarationException; } });
+var NativeLibraryNotFoundException_js_1 = require("../exceptions/NativeLibraryNotFoundException.js");
+Object.defineProperty(exports, "NativeLibraryNotFoundException", { enumerable: true, get: function () { return NativeLibraryNotFoundException_js_1.NativeLibraryNotFoundException; } });
+var NativeLibraryClosedException_js_1 = require("../exceptions/NativeLibraryClosedException.js");
+Object.defineProperty(exports, "NativeLibraryClosedException", { enumerable: true, get: function () { return NativeLibraryClosedException_js_1.NativeLibraryClosedException; } });
+var NativeMemoryException_js_1 = require("../exceptions/NativeMemoryException.js");
+Object.defineProperty(exports, "NativeMemoryException", { enumerable: true, get: function () { return NativeMemoryException_js_1.NativeMemoryException; } });
+var NativeCallback_js_1 = require("../lib/library/NativeCallback.js");
+Object.defineProperty(exports, "NativeCallback", { enumerable: true, get: function () { return NativeCallback_js_1.NativeCallback; } });
+var NativeLibraryHandle_js_1 = require("../lib/library/NativeLibraryHandle.js");
+Object.defineProperty(exports, "loadNativeLibrary", { enumerable: true, get: function () { return NativeLibraryHandle_js_1.loadNativeLibrary; } });
+Object.defineProperty(exports, "NativeLibraryHandle", { enumerable: true, get: function () { return NativeLibraryHandle_js_1.NativeLibraryHandle; } });
+var Memory_js_1 = require("../lib/Memory.js");
+Object.defineProperty(exports, "allocMemory", { enumerable: true, get: function () { return Memory_js_1.allocMemory; } });
+Object.defineProperty(exports, "freeMemory", { enumerable: true, get: function () { return Memory_js_1.freeMemory; } });
+Object.defineProperty(exports, "lastErrno", { enumerable: true, get: function () { return Memory_js_1.lastErrno; } });
+Object.defineProperty(exports, "lastWindowsError", { enumerable: true, get: function () { return Memory_js_1.lastWindowsError; } });
+Object.defineProperty(exports, "readArray", { enumerable: true, get: function () { return Memory_js_1.readArray; } });
+Object.defineProperty(exports, "readBuffer", { enumerable: true, get: function () { return Memory_js_1.readBuffer; } });
+Object.defineProperty(exports, "readCString", { enumerable: true, get: function () { return Memory_js_1.readCString; } });
+Object.defineProperty(exports, "readValue", { enumerable: true, get: function () { return Memory_js_1.readValue; } });
+Object.defineProperty(exports, "readWString", { enumerable: true, get: function () { return Memory_js_1.readWString; } });
+Object.defineProperty(exports, "sizeOf", { enumerable: true, get: function () { return Memory_js_1.sizeOf; } });
+Object.defineProperty(exports, "viewBuffer", { enumerable: true, get: function () { return Memory_js_1.viewBuffer; } });
+Object.defineProperty(exports, "writeValue", { enumerable: true, get: function () { return Memory_js_1.writeValue; } });
+var Library_js_1 = require("../decorators/Library.js");
+Object.defineProperty(exports, "Library", { enumerable: true, get: function () { return Library_js_1.Library; } });
+var Native_js_1 = require("../decorators/Native.js");
+Object.defineProperty(exports, "Native", { enumerable: true, get: function () { return Native_js_1.Native; } });
+Object.defineProperty(exports, "NativeVariable", { enumerable: true, get: function () { return Native_js_1.NativeVariable; } });
+var NativeLibrary_js_1 = require("../components/NativeLibrary.js");
+Object.defineProperty(exports, "buildNativeLibraryOptions", { enumerable: true, get: function () { return NativeLibrary_js_1.buildNativeLibraryOptions; } });
+Object.defineProperty(exports, "NativeLibrary", { enumerable: true, get: function () { return NativeLibrary_js_1.NativeLibrary; } });
+
+//The default of the entry: the entry itself (scripts/package-build/cjs-package.mjs)
+if (!Object.prototype.hasOwnProperty.call(exports, 'default')) Object.defineProperty(exports, 'default', {value: exports})

package/dist/cjs/exports/Generator.d.ts

@@ -0,0 +1,2 @@
+export { generateNativeLibrary, type GeneratedLibrary, type GenerateOptions, type GenerationReport, type SkippedDeclaration } from '../lib/generator/Generator.js';
+export { defaultCompiler, type PreprocessOptions } from '../lib/generator/Preprocessor.js';

package/dist/cjs/exports/Generator.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defaultCompiler = exports.generateNativeLibrary = void 0;
+var Generator_js_1 = require("../lib/generator/Generator.js");
+Object.defineProperty(exports, "generateNativeLibrary", { enumerable: true, get: function () { return Generator_js_1.generateNativeLibrary; } });
+var Preprocessor_js_1 = require("../lib/generator/Preprocessor.js");
+Object.defineProperty(exports, "defaultCompiler", { enumerable: true, get: function () { return Preprocessor_js_1.defaultCompiler; } });
+
+//The default of the entry: the entry itself (scripts/package-build/cjs-package.mjs)
+if (!Object.prototype.hasOwnProperty.call(exports, 'default')) Object.defineProperty(exports, 'default', {value: exports})

package/dist/cjs/lib/Memory.d.ts

@@ -0,0 +1,188 @@
+import { type Pointer } from './Runtime.js';
+/**
+ * An output parameter of a pointer or an integer: an array of one element, null before the call, set by the function
+ * (`[null]` given to `_Out_ sqlite3 **db`, then `db[0]`)
+ */
+export type Out<T> = [T | null];
+/**
+ * Read a C string (UTF-8, ended by a NUL byte) from native memory: a `char *` given as a pointer (a `void *` result, an
+ * argument of a callback, a member of a struct).
+ * @param pointer Its address.
+ * @param length Its length in bytes, when it is not ended by a NUL byte.
+ * @returns The string.
+ * @example
+ * ```typescript
+ * import {readCString, type Pointer} from '@lakutata/ffi'
+ *
+ * export function messageOf(pointer: Pointer): string {
+ *     return readCString(pointer)
+ * }
+ * ```
+ */
+export declare function readCString(pointer: Pointer, length?: number): string;
+/**
+ * Read a wide string from native memory: a `wchar_t *` (UTF-16 on Windows, UTF-32 elsewhere), ended by a NUL character.
+ * @param pointer Its address.
+ * @param length Its length in characters, when it is not ended by a NUL character.
+ * @returns The string.
+ * @example
+ * ```typescript
+ * import {readWString, type Pointer} from '@lakutata/ffi'
+ *
+ * export function titleOf(pointer: Pointer): string {
+ *     return readWString(pointer)
+ * }
+ * ```
+ */
+export declare function readWString(pointer: Pointer, length?: number): string;
+/**
+ * Copy native memory into a buffer of its own, which stays valid once the native memory is freed (about 10 GB/s).
+ * @param pointer The address of the memory.
+ * @param length Its length in bytes.
+ * @returns The copy.
+ * @example
+ * ```typescript
+ * import {readBuffer, type Pointer} from '@lakutata/ffi'
+ *
+ * export function frameOf(pixels: Pointer, width: number, height: number): Buffer {
+ *     return readBuffer(pixels, width * height * 4)
+ * }
+ * ```
+ */
+export declare function readBuffer(pointer: Pointer, length: number): Buffer;
+/**
+ * A view of native memory, without copy: worth it for large blocks read often (8 MiB: about 0.13 ms rather than 1 ms
+ * for a copy). The view must not be used once the native memory is freed: the process would crash. Electron forbids
+ * these views: it throws there (use readBuffer).
+ * @param pointer The address of the memory.
+ * @param length Its length in bytes.
+ * @returns The memory, as an ArrayBuffer.
+ * @throws {NativeMemoryException} In Electron, or for a null pointer.
+ * @example
+ * ```typescript
+ * import {viewBuffer, type Pointer} from '@lakutata/ffi'
+ *
+ * export function firstPixel(pixels: Pointer): number {
+ *     return new Uint32Array(viewBuffer(pixels, 4))[0]
+ * }
+ * ```
+ */
+export declare function viewBuffer(pointer: Pointer, length: number): ArrayBuffer;
+/**
+ * Read a value of a built-in type from native memory (`int`, `double`, `uint64_t`, `char *`…): the 64-bit integers as
+ * bigints. The types of a library are read by `read()` of the library.
+ * @param pointer Its address.
+ * @param type Its type.
+ * @returns The value.
+ * @example
+ * ```typescript
+ * import {readValue, type Pointer} from '@lakutata/ffi'
+ *
+ * export function countAt(pointer: Pointer): number {
+ *     return readValue(pointer, 'int32_t') as number
+ * }
+ * ```
+ */
+export declare function readValue(pointer: Pointer, type: string): unknown;
+/**
+ * Read an array of values of a built-in type from native memory.
+ * @param pointer The address of its first element.
+ * @param type The type of its elements (`char *` reads strings).
+ * @param count Its length.
+ * @returns The values.
+ * @example
+ * ```typescript
+ * import {readArray, type Pointer} from '@lakutata/ffi'
+ *
+ * //The row of a callback of sqlite3_exec: char **values
+ * export function rowOf(values: Pointer, count: number): string[] {
+ *     return readArray(values, 'char *', count) as string[]
+ * }
+ * ```
+ */
+export declare function readArray(pointer: Pointer, type: string, count: number): unknown[];
+/**
+ * Write a value of a built-in type to native memory.
+ * @param pointer Its address.
+ * @param type Its type.
+ * @param value The value.
+ * @example
+ * ```typescript
+ * import {allocMemory, freeMemory, readValue, writeValue} from '@lakutata/ffi'
+ *
+ * const counter: bigint = allocMemory('int64_t')
+ * writeValue(counter, 'int64_t', 42n)
+ * console.log(readValue(counter, 'int64_t'))
+ * freeMemory(counter)
+ * ```
+ */
+export declare function writeValue(pointer: Pointer, type: string, value: unknown): void;
+/**
+ * Allocate native memory for values of a built-in type: memory that does not move, which a library can keep (a buffer
+ * given to a function is valid during the call only). Freed by freeMemory.
+ * @param type The type of the values.
+ * @param count Their number.
+ * @returns Its address.
+ * @example
+ * ```typescript
+ * import {allocMemory, freeMemory} from '@lakutata/ffi'
+ *
+ * const buffer: bigint = allocMemory('uint8_t', 4096)
+ * freeMemory(buffer)
+ * ```
+ */
+export declare function allocMemory(type: string, count?: number): Pointer;
+/**
+ * Free native memory allocated by allocMemory.
+ * @param pointer Its address.
+ * @example
+ * ```typescript
+ * import {allocMemory, freeMemory} from '@lakutata/ffi'
+ *
+ * freeMemory(allocMemory('double', 16))
+ * ```
+ */
+export declare function freeMemory(pointer: Pointer): void;
+/**
+ * The size of a built-in type on the platform, in bytes (`long` is 8 on 64-bit Linux and macOS, 4 on Windows).
+ * @param type The type.
+ * @returns Its size.
+ * @example
+ * ```typescript
+ * import {sizeOf} from '@lakutata/ffi'
+ *
+ * console.log(sizeOf('long'), sizeOf('wchar_t'), sizeOf('void *'))
+ * ```
+ */
+export declare function sizeOf(type: string): number;
+/**
+ * The errno of the last native call of the thread. On Windows, each C library has its own errno: the one of the C
+ * library of Microsoft (ucrtbase.dll) by default.
+ * @param crt On Windows, the C library the function called uses (`msvcrt.dll` for the old libraries).
+ * @returns The errno.
+ * @example
+ * ```typescript
+ * import {lastErrno, loadNativeLibrary} from '@lakutata/ffi'
+ *
+ * const libc = loadNativeLibrary('c')
+ * const open = libc.func<(path: string, flags: number) => number>('int open(const char *path, int flags, ...)')
+ * if (open('/surely/missing', 0) < 0) console.log('errno', lastErrno())
+ * ```
+ */
+export declare function lastErrno(crt?: string): number;
+/**
+ * The last error of the Windows API of the thread (GetLastError), kept after each native call; undefined on the other
+ * systems.
+ * @returns The error.
+ * @example
+ * ```typescript
+ * import {lastWindowsError, loadNativeLibrary} from '@lakutata/ffi'
+ *
+ * if (process.platform === 'win32') {
+ *     const kernel32 = loadNativeLibrary('kernel32.dll')
+ *     const attributes = kernel32.func<(path: string) => number>('DWORD WINAPI GetFileAttributesW(LPCWSTR path)')
+ *     if (attributes('C:\\missing') === 0xFFFFFFFF) console.log('error', lastWindowsError())
+ * }
+ * ```
+ */
+export declare function lastWindowsError(): number | undefined;

package/dist/cjs/lib/Memory.js

@@ -0,0 +1,227 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readCString = readCString;
+exports.readWString = readWString;
+exports.readBuffer = readBuffer;
+exports.viewBuffer = viewBuffer;
+exports.readValue = readValue;
+exports.readArray = readArray;
+exports.writeValue = writeValue;
+exports.allocMemory = allocMemory;
+exports.freeMemory = freeMemory;
+exports.sizeOf = sizeOf;
+exports.lastErrno = lastErrno;
+exports.lastWindowsError = lastWindowsError;
+const koffi_1 = __importDefault(require("koffi"));
+const Runtime_js_1 = require("./Runtime.js");
+/**
+ * Read a C string (UTF-8, ended by a NUL byte) from native memory: a `char *` given as a pointer (a `void *` result, an
+ * argument of a callback, a member of a struct).
+ * @param pointer Its address.
+ * @param length Its length in bytes, when it is not ended by a NUL byte.
+ * @returns The string.
+ * @example
+ * ```typescript
+ * import {readCString, type Pointer} from '@lakutata/ffi'
+ *
+ * export function messageOf(pointer: Pointer): string {
+ *     return readCString(pointer)
+ * }
+ * ```
+ */
+function readCString(pointer, length) {
+    const address = (0, Runtime_js_1.checkedPointer)(pointer, 'readCString');
+    return length === undefined ? koffi_1.default.decode.string(address) : koffi_1.default.decode.string(address, length);
+}
+/**
+ * Read a wide string from native memory: a `wchar_t *` (UTF-16 on Windows, UTF-32 elsewhere), ended by a NUL character.
+ * @param pointer Its address.
+ * @param length Its length in characters, when it is not ended by a NUL character.
+ * @returns The string.
+ * @example
+ * ```typescript
+ * import {readWString, type Pointer} from '@lakutata/ffi'
+ *
+ * export function titleOf(pointer: Pointer): string {
+ *     return readWString(pointer)
+ * }
+ * ```
+ */
+function readWString(pointer, length) {
+    const address = (0, Runtime_js_1.checkedPointer)(pointer, 'readWString');
+    return length === undefined ? koffi_1.default.decode.wstring(address) : koffi_1.default.decode.wstring(address, length);
+}
+/**
+ * Copy native memory into a buffer of its own, which stays valid once the native memory is freed (about 10 GB/s).
+ * @param pointer The address of the memory.
+ * @param length Its length in bytes.
+ * @returns The copy.
+ * @example
+ * ```typescript
+ * import {readBuffer, type Pointer} from '@lakutata/ffi'
+ *
+ * export function frameOf(pixels: Pointer, width: number, height: number): Buffer {
+ *     return readBuffer(pixels, width * height * 4)
+ * }
+ * ```
+ */
+function readBuffer(pointer, length) {
+    return (0, Runtime_js_1.copyBuffer)(pointer, length);
+}
+/**
+ * A view of native memory, without copy: worth it for large blocks read often (8 MiB: about 0.13 ms rather than 1 ms
+ * for a copy). The view must not be used once the native memory is freed: the process would crash. Electron forbids
+ * these views: it throws there (use readBuffer).
+ * @param pointer The address of the memory.
+ * @param length Its length in bytes.
+ * @returns The memory, as an ArrayBuffer.
+ * @throws {NativeMemoryException} In Electron, or for a null pointer.
+ * @example
+ * ```typescript
+ * import {viewBuffer, type Pointer} from '@lakutata/ffi'
+ *
+ * export function firstPixel(pixels: Pointer): number {
+ *     return new Uint32Array(viewBuffer(pixels, 4))[0]
+ * }
+ * ```
+ */
+function viewBuffer(pointer, length) {
+    return (0, Runtime_js_1.nativeView)(pointer, length);
+}
+/**
+ * Read a value of a built-in type from native memory (`int`, `double`, `uint64_t`, `char *`…): the 64-bit integers as
+ * bigints. The types of a library are read by `read()` of the library.
+ * @param pointer Its address.
+ * @param type Its type.
+ * @returns The value.
+ * @example
+ * ```typescript
+ * import {readValue, type Pointer} from '@lakutata/ffi'
+ *
+ * export function countAt(pointer: Pointer): number {
+ *     return readValue(pointer, 'int32_t') as number
+ * }
+ * ```
+ */
+function readValue(pointer, type) {
+    return (0, Runtime_js_1.readNative)(Runtime_js_1.BUILTIN_TYPES, pointer, type);
+}
+/**
+ * Read an array of values of a built-in type from native memory.
+ * @param pointer The address of its first element.
+ * @param type The type of its elements (`char *` reads strings).
+ * @param count Its length.
+ * @returns The values.
+ * @example
+ * ```typescript
+ * import {readArray, type Pointer} from '@lakutata/ffi'
+ *
+ * //The row of a callback of sqlite3_exec: char **values
+ * export function rowOf(values: Pointer, count: number): string[] {
+ *     return readArray(values, 'char *', count) as string[]
+ * }
+ * ```
+ */
+function readArray(pointer, type, count) {
+    return (0, Runtime_js_1.readNative)(Runtime_js_1.BUILTIN_TYPES, pointer, type, count);
+}
+/**
+ * Write a value of a built-in type to native memory.
+ * @param pointer Its address.
+ * @param type Its type.
+ * @param value The value.
+ * @example
+ * ```typescript
+ * import {allocMemory, freeMemory, readValue, writeValue} from '@lakutata/ffi'
+ *
+ * const counter: bigint = allocMemory('int64_t')
+ * writeValue(counter, 'int64_t', 42n)
+ * console.log(readValue(counter, 'int64_t'))
+ * freeMemory(counter)
+ * ```
+ */
+function writeValue(pointer, type, value) {
+    (0, Runtime_js_1.writeNative)(Runtime_js_1.BUILTIN_TYPES, pointer, type, value);
+}
+/**
+ * Allocate native memory for values of a built-in type: memory that does not move, which a library can keep (a buffer
+ * given to a function is valid during the call only). Freed by freeMemory.
+ * @param type The type of the values.
+ * @param count Their number.
+ * @returns Its address.
+ * @example
+ * ```typescript
+ * import {allocMemory, freeMemory} from '@lakutata/ffi'
+ *
+ * const buffer: bigint = allocMemory('uint8_t', 4096)
+ * freeMemory(buffer)
+ * ```
+ */
+function allocMemory(type, count = 1) {
+    return (0, Runtime_js_1.allocateNative)(Runtime_js_1.BUILTIN_TYPES, type, count);
+}
+/**
+ * Free native memory allocated by allocMemory.
+ * @param pointer Its address.
+ * @example
+ * ```typescript
+ * import {allocMemory, freeMemory} from '@lakutata/ffi'
+ *
+ * freeMemory(allocMemory('double', 16))
+ * ```
+ */
+function freeMemory(pointer) {
+    (0, Runtime_js_1.freeNative)(pointer);
+}
+/**
+ * The size of a built-in type on the platform, in bytes (`long` is 8 on 64-bit Linux and macOS, 4 on Windows).
+ * @param type The type.
+ * @returns Its size.
+ * @example
+ * ```typescript
+ * import {sizeOf} from '@lakutata/ffi'
+ *
+ * console.log(sizeOf('long'), sizeOf('wchar_t'), sizeOf('void *'))
+ * ```
+ */
+function sizeOf(type) {
+    return (0, Runtime_js_1.typeSize)(Runtime_js_1.BUILTIN_TYPES, type);
+}
+/**
+ * The errno of the last native call of the thread. On Windows, each C library has its own errno: the one of the C
+ * library of Microsoft (ucrtbase.dll) by default.
+ * @param crt On Windows, the C library the function called uses (`msvcrt.dll` for the old libraries).
+ * @returns The errno.
+ * @example
+ * ```typescript
+ * import {lastErrno, loadNativeLibrary} from '@lakutata/ffi'
+ *
+ * const libc = loadNativeLibrary('c')
+ * const open = libc.func<(path: string, flags: number) => number>('int open(const char *path, int flags, ...)')
+ * if (open('/surely/missing', 0) < 0) console.log('errno', lastErrno())
+ * ```
+ */
+function lastErrno(crt) {
+    return (0, Runtime_js_1.nativeErrno)(crt);
+}
+/**
+ * The last error of the Windows API of the thread (GetLastError), kept after each native call; undefined on the other
+ * systems.
+ * @returns The error.
+ * @example
+ * ```typescript
+ * import {lastWindowsError, loadNativeLibrary} from '@lakutata/ffi'
+ *
+ * if (process.platform === 'win32') {
+ *     const kernel32 = loadNativeLibrary('kernel32.dll')
+ *     const attributes = kernel32.func<(path: string) => number>('DWORD WINAPI GetFileAttributesW(LPCWSTR path)')
+ *     if (attributes('C:\\missing') === 0xFFFFFFFF) console.log('error', lastWindowsError())
+ * }
+ * ```
+ */
+function lastWindowsError() {
+    return (0, Runtime_js_1.nativeWindowsError)();
+}

package/dist/cjs/lib/Runtime.d.ts

@@ -0,0 +1,98 @@
+import { type KoffiType, KoffiTypes } from './backend/KoffiTypes.js';
+import { DeclarationParser } from './declarations/Parser.js';
+import type { CType } from './declarations/Types.js';
+/**
+ * The koffi types of the process: one per C type, whatever library declares it
+ */
+export declare const TYPES: KoffiTypes;
+/**
+ * A pointer to native memory: a bigint (its address), null for NULL
+ */
+export type Pointer = bigint;
+/**
+ * The C types read from their names, with the declarations of a library or the built-in types only
+ */
+export declare class TypeNames {
+    #private;
+    /**
+     * The type names of a library.
+     * @param parser Its declarations.
+     */
+    constructor(parser: DeclarationParser);
+    /**
+     * A type, from its name.
+     * @param text Its name: `int`, `struct timeval`, `const char *`.
+     */
+    type(text: string): CType;
+    /**
+     * The koffi type of a type name.
+     * @param text Its name.
+     */
+    koffi(text: string): KoffiType;
+}
+/**
+ * The type names of the built-in types (of no library)
+ */
+export declare const BUILTIN_TYPES: TypeNames;
+/**
+ * A pointer checked: not null, a bigint or a number
+ * @param pointer
+ * @param what
+ */
+export declare function checkedPointer(pointer: unknown, what: string): Pointer;
+/**
+ * A copy of native memory, in a buffer of its own.
+ * @param pointer The address of the memory.
+ * @param length Its length in bytes.
+ */
+export declare function copyBuffer(pointer: Pointer, length: number): Buffer;
+/**
+ * A view of native memory, without copy: refused in Electron, which forbids them (koffi would end the process).
+ * @param pointer The address of the memory.
+ * @param length Its length in bytes.
+ */
+export declare function nativeView(pointer: Pointer, length: number): ArrayBuffer;
+/**
+ * A value read from native memory, converted as the package gives values (64-bit integers as bigints).
+ * @param names The type names to read the type with.
+ * @param pointer The address.
+ * @param type The type name.
+ * @param count The number of values, for an array.
+ */
+export declare function readNative(names: TypeNames, pointer: Pointer, type: string, count?: number): unknown;
+/**
+ * A value written to native memory.
+ * @param names The type names to read the type with.
+ * @param pointer The address.
+ * @param type The type name.
+ * @param value The value.
+ */
+export declare function writeNative(names: TypeNames, pointer: Pointer, type: string, value: unknown): void;
+/**
+ * Native memory allocated for values of a type (C's malloc: freed by freeNative).
+ * @param names The type names to read the type with.
+ * @param type The type name.
+ * @param count The number of values.
+ */
+export declare function allocateNative(names: TypeNames, type: string, count?: number): Pointer;
+/**
+ * Free native memory allocated by allocateNative (or by the malloc of the C library the package is built with).
+ * @param pointer The address.
+ */
+export declare function freeNative(pointer: Pointer): void;
+/**
+ * The errno of the last call made by the thread: on Windows, the one of the C library of Microsoft (ucrtbase.dll), each
+ * C library having its own; elsewhere the one koffi keeps after each call.
+ * @param crt On Windows, the C library the function called uses.
+ */
+export declare function nativeErrno(crt?: string): number;
+/**
+ * The last error of the Windows API of the thread (GetLastError), kept by koffi after each call; undefined elsewhere.
+ */
+export declare function nativeWindowsError(): number | undefined;
+/**
+ * The size of a type on the platform, by its name.
+ * @param names The type names.
+ * @param type The type name.
+ */
+export declare function typeSize(names: TypeNames, type: string): number;