@lakutata/ffi 0.0.0-stage → 3.1.5

package/dist/types/lib/declarations/Types.d.ts

@@ -0,0 +1,173 @@
+import type { Platform } from './Platform.js';
+/**
+ * The arithmetic types of C, by their meaning (long is not int64: their sizes differ between the platforms)
+ */
+export type PrimitiveName = 'void' | 'bool' | 'char' | 'schar' | 'uchar' | 'short' | 'ushort' | 'int' | 'uint' | 'long' | 'ulong' | 'longlong' | 'ulonglong' | 'int8' | 'uint8' | 'int16' | 'uint16' | 'int32' | 'uint32' | 'int64' | 'uint64' | 'size' | 'ssize' | 'intptr' | 'uintptr' | 'ptrdiff' | 'char16' | 'char32' | 'wchar' | 'float' | 'double';
+/**
+ * How the arguments of a function are passed: different on 32-bit Windows only
+ */
+export type CallingConvention = 'cdecl' | 'stdcall' | 'fastcall' | 'thiscall';
+/**
+ * Which way a pointer argument carries its value: into the function, out of it (the object or the array given is
+ * filled once it returns), or both
+ */
+export type Direction = 'in' | 'out' | 'inout';
+export interface PrimitiveType {
+    readonly kind: 'primitive';
+    readonly name: PrimitiveName;
+}
+export interface PointerType {
+    readonly kind: 'pointer';
+    readonly to: CType;
+    /**
+     * Whether what it points to is const (const char * is a string given to the function)
+     */
+    readonly constTarget: boolean;
+}
+export interface ArrayType {
+    readonly kind: 'array';
+    readonly of: CType;
+    readonly length: number;
+}
+export interface Member {
+    /**
+     * Its name; the anonymous structs and unions inside a struct are named _0, _1… in the order of the struct
+     */
+    readonly name: string;
+    readonly type: CType;
+    /**
+     * The width of a bitfield
+     */
+    readonly bits?: number;
+    /**
+     * The alignment its aligned attribute asks for, in bytes
+     */
+    readonly align?: number;
+}
+/**
+ * A struct or a union. One without members is opaque (declared, not defined); it is completed in place when defined
+ */
+export interface RecordType {
+    readonly kind: 'struct' | 'union';
+    readonly tag?: string;
+    members?: Member[];
+    /**
+     * The alignment its members are capped at (#pragma pack, the packed attribute)
+     */
+    pack?: number;
+    /**
+     * The alignment its aligned attribute asks for, in bytes
+     */
+    align?: number;
+}
+export interface EnumType {
+    readonly kind: 'enum';
+    readonly tag?: string;
+    /**
+     * The integer type holding its values
+     */
+    readonly base: PrimitiveName;
+    readonly values: ReadonlyMap<string, bigint>;
+}
+export interface Parameter {
+    readonly name?: string;
+    readonly type: CType;
+    readonly direction: Direction;
+}
+export interface FunctionType {
+    readonly kind: 'function';
+    readonly result: CType;
+    readonly parameters: readonly Parameter[];
+    readonly variadic: boolean;
+    readonly convention: CallingConvention;
+}
+/**
+ * A C type, as the declarations describe it
+ */
+export type CType = PrimitiveType | PointerType | ArrayType | RecordType | EnumType | FunctionType;
+/**
+ * A function the library exports
+ */
+export interface FunctionDeclaration {
+    readonly name: string;
+    /**
+     * The name of its symbol in the library: its name, or the one of its __asm label
+     */
+    readonly symbol: string;
+    readonly type: FunctionType;
+}
+/**
+ * A variable the library exports
+ */
+export interface VariableDeclaration {
+    readonly name: string;
+    readonly symbol: string;
+    readonly type: CType;
+    readonly constant: boolean;
+}
+/**
+ * What a text of declarations declares
+ */
+export interface Declarations {
+    /**
+     * The typedefs
+     */
+    readonly types: Map<string, CType>;
+    /**
+     * The tags of the structs, unions and enums ("struct timeval")
+     */
+    readonly tags: Map<string, RecordType | EnumType>;
+    readonly functions: Map<string, FunctionDeclaration>;
+    readonly variables: Map<string, VariableDeclaration>;
+    /**
+     * The values of the enumerations, of the static constants and of the macros whose value is an integer
+     */
+    readonly constants: Map<string, bigint>;
+    /**
+     * The macros without arguments (#define): their tokens, empty for the ones that are removed where used (the
+     * markers of exported functions); null for the macros with arguments, which cannot be used
+     */
+    readonly macros: Map<string, MacroToken[] | null>;
+}
+/**
+ * A token of a macro: its kind and its text (and its value, for a number or a character)
+ */
+export interface MacroToken {
+    readonly kind: 'identifier' | 'number' | 'char' | 'string' | 'punctuator';
+    readonly text: string;
+    readonly value?: bigint;
+    readonly float?: boolean;
+}
+/**
+ * An empty set of declarations
+ */
+export declare function emptyDeclarations(): Declarations;
+export declare const VOID: PrimitiveType;
+/**
+ * The size of an arithmetic type, in bytes
+ * @param name
+ * @param platform
+ */
+export declare function primitiveSize(name: PrimitiveName, platform: Platform): number;
+/**
+ * Whether an arithmetic type is signed
+ * @param name
+ * @param platform
+ */
+export declare function primitiveSigned(name: PrimitiveName, platform: Platform): boolean;
+/**
+ * Whether an arithmetic type is an integer
+ * @param name
+ */
+export declare function primitiveInteger(name: PrimitiveName): boolean;
+/**
+ * Whether an integer type is 64-bit on one of the platforms at least: its values are bigints (long is 64-bit but on
+ * Windows, size_t but on 32-bit systems)
+ * @param name
+ */
+export declare function primitiveBig(name: PrimitiveName): boolean;
+/**
+ * A type, as C writes it (for the messages)
+ * @param type
+ */
+export declare function typeText(type: CType): string;

package/dist/types/lib/generator/CText.d.ts

@@ -0,0 +1,14 @@
+import type { Token } from '../declarations/Lexer.js';
+/**
+ * The tokens of a declaration without what changes nothing of what it declares: the attributes but packed and aligned,
+ * the __declspec but align, the qualifiers the parser ignores
+ * @param tokens
+ */
+export declare function prunedTokens(tokens: readonly Token[]): Token[];
+/**
+ * A declaration written as C, one member of a struct or a value of an enum by line
+ * @param tokens Its tokens.
+ * @param indent The indentation of a level.
+ * @returns Its lines.
+ */
+export declare function declarationText(tokens: readonly Token[], indent?: string): string[];

package/dist/types/lib/generator/Generator.d.ts

@@ -0,0 +1,136 @@
+import { type Platform } from '../declarations/Platform.js';
+import { type PreprocessedHeader, type PreprocessOptions } from './Preprocessor.js';
+/**
+ * How a library is generated from its header
+ */
+export interface GenerateOptions extends PreprocessOptions {
+    /**
+     * The library its functions are checked against: a name, as `@Library` takes it, or a file. The name of the header
+     * by default (`sqlite3.h`: `sqlite3`): give it when that library cannot be loaded (the report tells why the
+     * functions were not checked).
+     */
+    readonly library?: string;
+    /**
+     * The name of the class. The name of the header in PascalCase by default (`sqlite3.h`: `Sqlite3`).
+     */
+    readonly className?: string;
+    /**
+     * More directories whose headers are the ones of the library: the header is, and so are the headers of its
+     * directory when it is not a directory of the system.
+     */
+    readonly own?: readonly string[];
+    /**
+     * Whether the functions and the variables are checked against the library, the ones it cannot give left out.
+     * @default true
+     */
+    readonly check?: boolean;
+}
+/**
+ * A declaration of the header that was left out, and why
+ */
+export interface SkippedDeclaration {
+    /**
+     * Its name, or the start of its text
+     */
+    readonly name: string;
+    /**
+     * The file it comes from
+     */
+    readonly file?: string;
+    /**
+     * Its line in that file
+     */
+    readonly line?: number;
+    /**
+     * Why it was left out
+     */
+    readonly reason: string;
+}
+/**
+ * What the generation did
+ */
+export interface GenerationReport {
+    /**
+     * The command that ran the preprocessor
+     */
+    readonly command: string;
+    /**
+     * The platform the library was generated for (`darwin-arm64`)
+     */
+    readonly platform: string;
+    /**
+     * The file of the library the functions were checked against
+     */
+    readonly library?: string;
+    /**
+     * Why they were not checked
+     */
+    readonly unchecked?: string;
+    /**
+     * The functions of the class
+     */
+    readonly functions: number;
+    /**
+     * The variables of the class
+     */
+    readonly variables: number;
+    /**
+     * The interfaces of the structs and unions
+     */
+    readonly interfaces: number;
+    /**
+     * The constants of the declarations: the integer macros, the values of the enums, the static constants
+     */
+    readonly constants: number;
+    /**
+     * The declarations of the library left out: the ones that cannot be read, the functions and variables the library
+     * cannot give
+     */
+    readonly skipped: readonly SkippedDeclaration[];
+}
+/**
+ * A library generated from its header
+ */
+export interface GeneratedLibrary {
+    /**
+     * The name of its class
+     */
+    readonly className: string;
+    /**
+     * The TypeScript code of its class
+     */
+    readonly code: string;
+    /**
+     * Its C declarations, as the class gives them to `@Library`
+     */
+    readonly declarations: string;
+    /**
+     * What was generated, and what was left out
+     */
+    readonly report: GenerationReport;
+}
+/**
+ * Generate the class of a library from a header already run through the preprocessor (see generateNativeLibrary).
+ * @param preprocessed The output of the preprocessor, the header, the directories of the system.
+ * @param options The library, the class, the directories of the library.
+ * @param platform The platform the header was preprocessed for.
+ * @returns The code of the class and the report.
+ */
+export declare function generateFromPreprocessed(preprocessed: PreprocessedHeader, options?: Omit<GenerateOptions, 'header'>, platform?: Platform): Promise<GeneratedLibrary>;
+/**
+ * Generate the class of a native library from its header: the header is run through the preprocessor of the C compiler,
+ * its declarations are read, the functions and the variables the library cannot give are left out, and the class gets a
+ * property by function (named as the function) with its TypeScript type.
+ * @param options The header, the library, the class, the compiler and its options.
+ * @returns The code of the class, and what was generated and left out.
+ * @example
+ * ```typescript
+ * import {writeFileSync} from 'node:fs'
+ * import {generateNativeLibrary} from '@lakutata/ffi/generator'
+ *
+ * const {code, report} = await generateNativeLibrary({header: 'vendor/include/vendor.h', library: 'vendor/lib/libvendor.so'})
+ * writeFileSync('src/native/Vendor.ts', code)
+ * for (const skipped of report.skipped) console.log(`${skipped.name}: ${skipped.reason}`)
+ * ```
+ */
+export declare function generateNativeLibrary(options: GenerateOptions): Promise<GeneratedLibrary>;

package/dist/types/lib/generator/Preprocessor.d.ts

@@ -0,0 +1,60 @@
+/**
+ * How a header is run through the preprocessor
+ */
+export interface PreprocessOptions {
+    /**
+     * The header
+     */
+    readonly header: string;
+    /**
+     * The compiler whose preprocessor is run: cc, gcc, clang (their -E -dD), or cl, clang-cl (cl /P /d1PP)
+     */
+    readonly compiler?: string;
+    /**
+     * The directories of the headers it includes
+     */
+    readonly include?: readonly string[];
+    /**
+     * The macros defined before it: NAME, or NAME=VALUE
+     */
+    readonly define?: readonly string[];
+}
+/**
+ * A header run through the preprocessor
+ */
+export interface PreprocessedHeader {
+    /**
+     * The output of the preprocessor: the declarations, the #define kept, the line markers naming the files
+     */
+    readonly text: string;
+    /**
+     * The header, as the line markers name it
+     */
+    readonly header: string;
+    /**
+     * The directories of the headers of the system: their headers are not the ones of the library
+     */
+    readonly systemDirectories: readonly string[];
+    /**
+     * The command run
+     */
+    readonly command: string;
+}
+/**
+ * The C compiler whose preprocessor reads the headers by default: the one of the CC variable, else cl on Windows (run
+ * in the Developer Command Prompt of Visual Studio), cc elsewhere.
+ * @returns The command of the compiler.
+ * @example
+ * ```typescript
+ * import {defaultCompiler} from '@lakutata/ffi/generator'
+ *
+ * console.log(defaultCompiler())
+ * ```
+ */
+export declare function defaultCompiler(): string;
+/**
+ * Run a header through the preprocessor of a compiler, keeping its #define and the line markers naming the files.
+ * @param options The header, the compiler, the directories and the macros.
+ * @returns The output, the header as the line markers name it, the directories of the system.
+ */
+export declare function preprocessHeader(options: PreprocessOptions): PreprocessedHeader;

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