C library contracts
On this page
Import defineLibrary from @maligator/cli to declare the headers and facts that Maligator uses to bind a C library. Point the ffi build option at the contract file. The CLI loads and validates that file as trusted project code.
Use find to describe how to locate the library. Paths in the contract resolve from the contract file's directory. Set find in the build configuration's library entry to replace the contract's discovery alternatives on a particular machine.
Follow Bind a library to call C code from an application. Use maligator ffi inspect to see which declarations bind and which need more facts.
MaligatorFfiFind
How the build finds a C library's headers and binaries. Relative paths resolve
against the file that declares them. Name at least pkgConfig, libraries, or
sources; the other fields add to what those provide.
Full TypeScript declaration
export interface MaligatorFfiFind {
/** A pkg-config package that supplies include directories and linker inputs. */
pkgConfig?: string;
/** Header search directories. */
includeDirs?: Array<string>;
/** Preprocessor definitions for the headers and sources. */
defines?: Record<string, string>;
/** Directories searched for `libraries`. */
libraryDirs?: Array<string>;
/** Libraries linked by name, as with `-lname`. */
libraries?: Array<string>;
/** macOS frameworks to link, such as `Cocoa`. */
frameworks?: Array<string>;
/** C sources compiled into the program instead of a prebuilt library. */
sources?: Array<string>;
}MaligatorFfiFind.pkgConfig
A pkg-config package that supplies include directories and linker inputs.
pkgConfig?: string;MaligatorFfiFind.includeDirs
Header search directories.
includeDirs?: Array<string>;MaligatorFfiFind.defines
Preprocessor definitions for the headers and sources.
defines?: Record<string, string>;MaligatorFfiFind.libraryDirs
Directories searched for libraries.
libraryDirs?: Array<string>;MaligatorFfiFind.libraries
Libraries linked by name, as with -lname.
libraries?: Array<string>;MaligatorFfiFind.frameworks
macOS frameworks to link, such as Cocoa.
frameworks?: Array<string>;MaligatorFfiFind.sources
C sources compiled into the program instead of a prebuilt library.
sources?: Array<string>;MaligatorFfiHandle
A C resource or caller-owned state struct. Its handles
close on [Symbol.dispose]() or when passed to destroy; a closed handle throws
instead of reaching C.
Full TypeScript declaration
export interface MaligatorFfiHandle {
/** Export a factory named by the type fact. It allocates aligned,
* zeroed caller-owned storage. C initialization and cleanup
* remain explicit. With a collecting destructor, an `initializes` function arms
* cleanup; before initialization, disposal frees only the outer storage.
*/
storage?: "caller";
/** A final flexible or zero-length array field in caller storage. The factory
* takes its element count as a bigint; without this fact it takes no arguments.
* Allocation does not initialize a C count field.
*/
trailing?: string;
/** Native size and alignment queries for an incomplete struct. Both functions
* take no arguments and return unsigned integers up to 64 bits. The factory
* calls them for each allocation, checking size and alignment before allocating.
*/
layout?: { size: string; alignment: string };
/** Other handle types whose pointers accept this resource without adjustment.
* Compatibility is directed and preserves the resource's identity and owner.
*/
views?: Array<string>;
/** The function that releases the resource, taking it as its only parameter.
* A name asserts unconditional release. With `success`, release occurs only when
* its integer or boolean result equals the C identifier or integer literal.
*/
destroy?: string | { function: string; success: string };
/** Release a collected handle once its native result borrowers finish. The last lease
* may retire on a foreign thread. Off unless
* set; leave it off for resources that must be released on one thread or before the
* library shuts down. Conditional cleanup requires explicit disposal and retry.
*/
collect?: boolean;
}MaligatorFfiHandle.storage
Export a factory named by the type fact. It allocates aligned,
zeroed caller-owned storage. C initialization and cleanup
remain explicit. With a collecting destructor, an initializes function arms
cleanup; before initialization, disposal frees only the outer storage.
storage?: "caller";MaligatorFfiHandle.trailing
A final flexible or zero-length array field in caller storage. The factory takes its element count as a bigint; without this fact it takes no arguments. Allocation does not initialize a C count field.
trailing?: string;MaligatorFfiHandle.layout
Native size and alignment queries for an incomplete struct. Both functions take no arguments and return unsigned integers up to 64 bits. The factory calls them for each allocation, checking size and alignment before allocating.
Full TypeScript declaration
layout?: { size: string; alignment: string };MaligatorFfiHandle.layout.size
size: string;MaligatorFfiHandle.layout.alignment
alignment: stringMaligatorFfiHandle.views
Other handle types whose pointers accept this resource without adjustment. Compatibility is directed and preserves the resource's identity and owner.
views?: Array<string>;MaligatorFfiHandle.destroy
The function that releases the resource, taking it as its only parameter.
A name asserts unconditional release. With success, release occurs only when
its integer or boolean result equals the C identifier or integer literal.
Full TypeScript declaration
destroy?: string | { function: string; success: string };MaligatorFfiHandle.destroy.function
function: string;MaligatorFfiHandle.destroy.success
success: stringMaligatorFfiHandle.collect
Release a collected handle once its native result borrowers finish. The last lease may retire on a foreign thread. Off unless set; leave it off for resources that must be released on one thread or before the library shuts down. Conditional cleanup requires explicit disposal and retry.
collect?: boolean;MaligatorFfiTypeFacts
Facts about one C type, keyed by its typedef or tag.
Full TypeScript declaration
export interface MaligatorFfiTypeFacts {
/** Preserve an arithmetic typedef exactly in a nominal native value box. */
representation?: "native";
handle?: MaligatorFfiHandle;
/** Select active union storage explicitly or from a record's discriminator. */
shape?: MaligatorFfiShape;
/** Owned resource fields in value records, borrowed fields on handles, or retained ranges.
* Range assignment writes the pointer and count together; C may advance them only
* within the assigned range.
*/
fields?: Record<string, MaligatorFfiFieldFacts>;
/** Header documentation that `ffi check` watches when reviewing these facts. */
evidence?: Array<MaligatorFfiEvidence>;
}Types: MaligatorFfiHandle, MaligatorFfiFieldFacts, MaligatorFfiEvidence, MaligatorFfiShape
MaligatorFfiTypeFacts.representation
Preserve an arithmetic typedef exactly in a nominal native value box.
representation?: "native";MaligatorFfiTypeFacts.handle
handle?: MaligatorFfiHandle;Types: MaligatorFfiHandle
MaligatorFfiTypeFacts.shape
Select active union storage explicitly or from a record's discriminator.
shape?: MaligatorFfiShape;Types: MaligatorFfiShape
MaligatorFfiTypeFacts.fields
Owned resource fields in value records, borrowed fields on handles, or retained ranges. Range assignment writes the pointer and count together; C may advance them only within the assigned range.
fields?: Record<string, MaligatorFfiFieldFacts>;Types: MaligatorFfiFieldFacts
MaligatorFfiTypeFacts.evidence
Header documentation that ffi check watches when reviewing these facts.
evidence?: Array<MaligatorFfiEvidence>;Types: MaligatorFfiEvidence
MaligatorFfiFieldFacts
A resource, callable or counted array field, or a range retained by caller-owned state.
export type MaligatorFfiFieldFacts =
| {
bytes: {
/** The C integer field holding the remaining byte count. */
length: string;
/** Whether C writes these bytes; defaults to true for a non-const pointee. */
writable?: boolean;
};
string?: never;
callable?: never;
handle?: never;
array?: never;
value?: never;
}
| {
/** UTF-8 text kept in a private encoding, with a C field holding its byte count. */
string: MaligatorFfiCount;
bytes?: never;
callable?: never;
handle?: never;
array?: never;
value?: never;
}
| {
callable: MaligatorFfiCallable;
bytes?: never;
string?: never;
handle?: never;
array?: never;
value?: never;
}
| {
/** Owned fields transfer from value results; record inputs borrow their handles.
* Borrowed accessor lifetime follows its owner or the C library's process storage.
*/
handle:
| { lifetime: "owner" | "library"; owned?: never; fresh?: never }
| { owned: true; fresh?: boolean; lifetime?: never };
bytes?: never;
string?: never;
callable?: never;
array?: never;
value?: never;
}
| {
/**
* A pointer to values on any handle, read as a fresh array of as many elements as
* the C integer field `length` holds; `null` for a null pointer.
*/
array: MaligatorFfiCount;
bytes?: never;
string?: never;
callable?: never;
handle?: never;
value?: never;
}
| {
/**
* Expose this value member as a read-only property on any handle, including a
* library-owned pointer handle whose other members stay hidden.
*/
value: true;
bytes?: never;
string?: never;
callable?: never;
handle?: never;
array?: never;
};Types: MaligatorFfiCount, MaligatorFfiCallable
MaligatorFfiEvidence
A declaration whose documentation supports a fact, independent of its source location.
Full TypeScript declaration
export interface MaligatorFfiEvidence {
kind: "function" | "global" | "typedef" | "struct" | "union" | "enum" | "macro";
name: string;
}MaligatorFfiEvidence.kind
kind: "function" | "global" | "typedef" | "struct" | "union" | "enum" | "macro";MaligatorFfiEvidence.name
name: string;MaligatorFfiCount
The C parameter or state field carrying a byte or element count.
Full TypeScript declaration
export interface MaligatorFfiCount {
/**
* The parameter's C name, or its 1-based position. For a result, the count comes
* from an integer parameter or from an integer the function writes through a pointer.
* Callback counts use 1-based positions.
* State counts use C field names; global counts use C object names.
* An input buffer or array of a function can instead require a minimum length, a
* product of integer parameters and literals such as `"width * height * 4"`; those
* parameters stay in the JavaScript signature.
*/
length: string;
}MaligatorFfiCount.length
The parameter's C name, or its 1-based position. For a result, the count comes
from an integer parameter or from an integer the function writes through a pointer.
Callback counts use 1-based positions.
State counts use C field names; global counts use C object names.
An input buffer or array of a function can instead require a minimum length, a
product of integer parameters and literals such as "width * height * 4"; those
parameters stay in the JavaScript signature.
length: string;MaligatorFfiShape
Select active C union storage explicitly or through an integer discriminator.
export type MaligatorFfiShape =
| { member: string }
| {
/** A direct or anonymously promoted C integer field. */
tag: string;
/** Integer constants map to paths naming the active C union members. */
cases: Readonly<Record<string, ReadonlyArray<string>>>;
};MaligatorFfiValueFacts
Facts about a parameter or a result.
Full TypeScript declaration
export interface MaligatorFfiValueFacts {
/** Override the active union shape for this value or array element. */
shape?: MaligatorFfiShape;
/** Accept `null` for a pointer parameter and pass `NULL`. */
nullable?: boolean;
/** A returned/output handle or flat pointer array whose pointees the library keeps
* owning. Closing a borrowed wrapper does not release its resource. Caller pointer
* buffers require an explicit choice: `false` transfers pointee ownership.
*/
borrowed?: boolean;
/** A pointer result starts a new resource lifetime, rather than aliasing an
* existing handle. This distinguishes a reused address during worker cleanup.
*/
fresh?: boolean;
/** The function writes a value through this pointer; it returns beside the result. */
out?: boolean;
/** The function reads and updates the value behind this pointer; the new value returns beside the result. */
inout?: boolean;
/** UTF-8 text in a char pointer. `true` uses NUL termination; a length names
* its byte count and permits embedded NUL bytes. Out strings use a count pointer C
* fills. Inout strings borrow an encoding through conversion of the updated value.
* Queued notifications copy the counted bytes; waiting callbacks borrow them.
*/
string?: boolean | MaligatorFfiCount;
/** Bytes passed as an `ArrayBuffer` or a view, or returned as a new `Uint8Array`. */
bytes?: MaligatorFfiCount;
/** Elements passed or returned as an array. For an out buffer, `capacity` names
* an integer input that bounds caller-owned storage; it stays in the JS signature.
*/
array?: MaligatorFfiCount & {
capacity?: string;
/** Decode fixed character rows as bounded UTF-8 text or exact byte views. */
element?: { string: true; bytes?: never } | { bytes: true; string?: never };
/**
* Lend a matching typed array, such as a `Float64Array` for `double *`, for C
* to write in place during a synchronous call. Ordinary arrays still pass a copy.
*/
writable?: true;
};
/** Release a copied string, buffer, or array result with this function. */
free?: string;
/** A function pointer the library calls during the call with a JavaScript function. */
callback?: MaligatorFfiCallback;
/** A returned C function pointer, callable with its declared header signature. */
callable?: MaligatorFfiCallable;
/**
* Pass this C macro, enumerator, or integer, such as `SQLITE_TRANSIENT` or `0`, and
* drop the parameter from the JavaScript signature. The C compiler checks its type.
*/
constant?: string;
/** Pass the C compiler's `sizeof` for this complete struct or union type and
* omit the parameter from JavaScript. Its size must fit the integer parameter.
*/
sizeof?: string;
/**
* The C type a `void *` or `const void *` parameter points at, such as `double`, when
* another argument selects it at runtime. The parameter then binds as a pointer to
* that type, keeping its constness; pair it with per-type `variants`.
*/
pointee?: string;
/**
* Pass the address of the terminator of the NUL-terminated string that this
* parameter, named by C name or 1-based position, passes, and omit this parameter
* from JavaScript. C then reads that text as a `[start, end)` range.
*/
end?: string;
}Types: MaligatorFfiCount, MaligatorFfiShape, MaligatorFfiCallable, MaligatorFfiCallback
MaligatorFfiValueFacts.shape
Override the active union shape for this value or array element.
shape?: MaligatorFfiShape;Types: MaligatorFfiShape
MaligatorFfiValueFacts.nullable
Accept null for a pointer parameter and pass NULL.
nullable?: boolean;MaligatorFfiValueFacts.borrowed
A returned/output handle or flat pointer array whose pointees the library keeps
owning. Closing a borrowed wrapper does not release its resource. Caller pointer
buffers require an explicit choice: false transfers pointee ownership.
borrowed?: boolean;MaligatorFfiValueFacts.fresh
A pointer result starts a new resource lifetime, rather than aliasing an existing handle. This distinguishes a reused address during worker cleanup.
fresh?: boolean;MaligatorFfiValueFacts.out
The function writes a value through this pointer; it returns beside the result.
out?: boolean;MaligatorFfiValueFacts.inout
The function reads and updates the value behind this pointer; the new value returns beside the result.
inout?: boolean;MaligatorFfiValueFacts.string
UTF-8 text in a char pointer. true uses NUL termination; a length names
its byte count and permits embedded NUL bytes. Out strings use a count pointer C
fills. Inout strings borrow an encoding through conversion of the updated value.
Queued notifications copy the counted bytes; waiting callbacks borrow them.
string?: boolean | MaligatorFfiCount;Types: MaligatorFfiCount
MaligatorFfiValueFacts.bytes
Bytes passed as an ArrayBuffer or a view, or returned as a new Uint8Array.
bytes?: MaligatorFfiCount;Types: MaligatorFfiCount
MaligatorFfiValueFacts.array
Elements passed or returned as an array. For an out buffer, capacity names
an integer input that bounds caller-owned storage; it stays in the JS signature.
Full TypeScript declaration
array?: MaligatorFfiCount & {
capacity?: string;
/** Decode fixed character rows as bounded UTF-8 text or exact byte views. */
element?: { string: true; bytes?: never } | { bytes: true; string?: never };
/**
* Lend a matching typed array, such as a `Float64Array` for `double *`, for C
* to write in place during a synchronous call. Ordinary arrays still pass a copy.
*/
writable?: true;
};Types: MaligatorFfiCount
MaligatorFfiValueFacts.array.capacity
capacity?: string;MaligatorFfiValueFacts.array.element
Decode fixed character rows as bounded UTF-8 text or exact byte views.
Full TypeScript declaration
element?: { string: true; bytes?: never } | { bytes: true; string?: never };MaligatorFfiValueFacts.array.element.string
string: true;MaligatorFfiValueFacts.array.element.bytes
bytes?: neverMaligatorFfiValueFacts.array.writable
Lend a matching typed array, such as a Float64Array for double *, for C
to write in place during a synchronous call. Ordinary arrays still pass a copy.
writable?: true;MaligatorFfiValueFacts.free
Release a copied string, buffer, or array result with this function.
free?: string;MaligatorFfiValueFacts.callback
A function pointer the library calls during the call with a JavaScript function.
callback?: MaligatorFfiCallback;Types: MaligatorFfiCallback
MaligatorFfiValueFacts.callable
A returned C function pointer, callable with its declared header signature.
callable?: MaligatorFfiCallable;Types: MaligatorFfiCallable
MaligatorFfiValueFacts.constant
Pass this C macro, enumerator, or integer, such as SQLITE_TRANSIENT or 0, and
drop the parameter from the JavaScript signature. The C compiler checks its type.
constant?: string;MaligatorFfiValueFacts.sizeof
Pass the C compiler's sizeof for this complete struct or union type and
omit the parameter from JavaScript. Its size must fit the integer parameter.
sizeof?: string;MaligatorFfiValueFacts.pointee
The C type a void * or const void * parameter points at, such as double, when
another argument selects it at runtime. The parameter then binds as a pointer to
that type, keeping its constness; pair it with per-type variants.
pointee?: string;MaligatorFfiValueFacts.end
Pass the address of the terminator of the NUL-terminated string that this
parameter, named by C name or 1-based position, passes, and omit this parameter
from JavaScript. C then reads that text as a [start, end) range.
end?: string;MaligatorFfiCallable
A C function whose code and referenced state remain valid for its lifetime.
Full TypeScript declaration
export interface MaligatorFfiCallable {
/** Owner lifetime captures the handle whose function-table field was read. */
lifetime: "library" | "owner";
/** Facts keyed by the signature's 1-based parameter positions. */
params?: Record<string, MaligatorFfiValueFacts>;
returns?: MaligatorFfiValueFacts;
}Types: MaligatorFfiValueFacts
MaligatorFfiCallable.lifetime
Owner lifetime captures the handle whose function-table field was read.
lifetime: "library" | "owner";MaligatorFfiCallable.params
Facts keyed by the signature's 1-based parameter positions.
params?: Record<string, MaligatorFfiValueFacts>;Types: MaligatorFfiValueFacts
MaligatorFfiCallable.returns
returns?: MaligatorFfiValueFacts;Types: MaligatorFfiValueFacts
MaligatorFfiCallback
A callback the library calls before the function returns, such as an iteration or comparison function, until it releases the callback, until the next call replaces it, or to complete a handle's close. An exception it throws skips later calls and rethrows when the C function the library runs in returns.
Full TypeScript declaration
export interface MaligatorFfiCallback {
/**
* The input handle whose destruction root owns the registration, by C name or
* 1-based position, for a callback kept through `release` or `replaced`.
* Destruction must stop the callback and all its consumers before returning. Its closure and borrowed inputs share that root's lifetime. The root
* must be an independently owned library allocation with a destructor.
*/
owner?: string;
/** Native copies or resource leases remain valid for the declared lifetime. */
returns?: MaligatorFfiCallbackResult;
/**
* The `void *` parameter the library passes back to the callback, by C name or
* 1-based position. Without it, a callback the library calls only during the
* function, such as `qsort`'s comparator, still binds, as does a `replaced` one.
*/
data?: string;
/**
* The `void (*)(void *)` parameter that takes the destructor for `data`, by C name or
* 1-based position. The library may then keep calling the callback after the
* function returns, until it calls the destructor.
*/
release?: string;
/**
* The library keeps the callback until the next call of the function replaces it,
* as setters such as `glfwSetErrorCallback` do. When the first parameter is a
* handle, each handle keeps its own callback until its resource is destroyed.
* Another setter for the same key throws while its setter is pending.
*/
replaced?: boolean;
/**
* The input handle whose lifetime ends when this one-shot completion runs, by C
* name or 1-based position. Its storage and retained buffers survive until then.
* The wrapper is closed before JavaScript runs; foreign completions queue for it.
* An async twin settles at C return and requires a handle the program already holds.
*/
closes?: string;
/**
* For a callback without a `void *` parameter: the function that returns `data`
* from the callback's parameter at 1-based position `param`, such as
* `sqlite3_user_data` for SQLite's `sqlite3_context *`.
*/
lookup?: { function: string; param: string };
/**
* The library may call the kept callback from other threads. `true` copies arguments
* and queues for the program's thread, letting C continue with a void result.
* `"wait"` borrows pointed-to arguments while blocking C until JavaScript returns
* a result. Pointer results need an explicit lifetime. Handles are lent only for that
* callback. The program needs an event loop, which waits while the callback is kept. Stop or join the
* producer asynchronously; the program's thread must remain free to run callbacks.
*/
queued?: boolean | "wait";
/**
* Facts per callback parameter, keyed by 1-based position: `string`, `bytes`, or
* `array` with a `length` naming another callback parameter, `nullable`, and `shape`.
*/
params?: Record<string, MaligatorFfiValueFacts>;
/**
* The library calls the callback exactly once, during or after the function, and
* then drops it, as WebGPU's request functions do. Needs `data` or `lookup`.
*/
once?: boolean;
/**
* On a struct parameter passed by value, such as WebGPU's callback info records: the
* function pointer member that receives the callback. `data` then names the `void *`
* member for the registration, and the parameter takes a JavaScript function.
*/
field?: string;
/** C identifiers or integer literals for other members of a `field` record; the rest start zeroed. */
constants?: Record<string, string>;
}MaligatorFfiCallback.owner
The input handle whose destruction root owns the registration, by C name or
1-based position, for a callback kept through release or replaced.
Destruction must stop the callback and all its consumers before returning. Its closure and borrowed inputs share that root's lifetime. The root
must be an independently owned library allocation with a destructor.
owner?: string;MaligatorFfiCallback.returns
Native copies or resource leases remain valid for the declared lifetime.
returns?: MaligatorFfiCallbackResult;Types: MaligatorFfiCallbackResult
MaligatorFfiCallback.data
The void * parameter the library passes back to the callback, by C name or
1-based position. Without it, a callback the library calls only during the
function, such as qsort's comparator, still binds, as does a replaced one.
data?: string;MaligatorFfiCallback.release
The void (*)(void *) parameter that takes the destructor for data, by C name or
1-based position. The library may then keep calling the callback after the
function returns, until it calls the destructor.
release?: string;MaligatorFfiCallback.replaced
The library keeps the callback until the next call of the function replaces it,
as setters such as glfwSetErrorCallback do. When the first parameter is a
handle, each handle keeps its own callback until its resource is destroyed.
Another setter for the same key throws while its setter is pending.
replaced?: boolean;MaligatorFfiCallback.closes
The input handle whose lifetime ends when this one-shot completion runs, by C name or 1-based position. Its storage and retained buffers survive until then. The wrapper is closed before JavaScript runs; foreign completions queue for it. An async twin settles at C return and requires a handle the program already holds.
closes?: string;MaligatorFfiCallback.lookup
For a callback without a void * parameter: the function that returns data
from the callback's parameter at 1-based position param, such as
sqlite3_user_data for SQLite's sqlite3_context *.
Full TypeScript declaration
lookup?: { function: string; param: string };MaligatorFfiCallback.lookup.function
function: string;MaligatorFfiCallback.lookup.param
param: stringMaligatorFfiCallback.queued
The library may call the kept callback from other threads. true copies arguments
and queues for the program's thread, letting C continue with a void result.
"wait" borrows pointed-to arguments while blocking C until JavaScript returns
a result. Pointer results need an explicit lifetime. Handles are lent only for that
callback. The program needs an event loop, which waits while the callback is kept. Stop or join the
producer asynchronously; the program's thread must remain free to run callbacks.
queued?: boolean | "wait";MaligatorFfiCallback.params
Facts per callback parameter, keyed by 1-based position: string, bytes, or
array with a length naming another callback parameter, nullable, and shape.
params?: Record<string, MaligatorFfiValueFacts>;Types: MaligatorFfiValueFacts
MaligatorFfiCallback.once
The library calls the callback exactly once, during or after the function, and
then drops it, as WebGPU's request functions do. Needs data or lookup.
once?: boolean;MaligatorFfiCallback.field
On a struct parameter passed by value, such as WebGPU's callback info records: the
function pointer member that receives the callback. data then names the void *
member for the registration, and the parameter takes a JavaScript function.
field?: string;MaligatorFfiCallback.constants
C identifiers or integer literals for other members of a field record; the rest start zeroed.
constants?: Record<string, string>;MaligatorFfiCallbackResult
A callback result's value shape, or the lifetime of a returned pointer.
export type MaligatorFfiCallbackResult =
| {
shape: MaligatorFfiShape;
lifetime?: never;
string?: never;
bytes?: never;
nullable?: never;
}
| (Pick<MaligatorFfiValueFacts, "string" | "bytes" | "nullable"> & {
/** C stops using every result before the call returns or the registration ends,
* including pointers held by pending consumers. Self-release forbids another non-null result. */
lifetime: "call" | "registration";
shape?: never;
});Types: MaligatorFfiShape, MaligatorFfiValueFacts
MaligatorFfiFunctionFacts
Facts about one C function, keyed by its name.
Full TypeScript declaration
export interface MaligatorFfiFunctionFacts {
/**
* Audited fact that native execution never enters JavaScript, including through
* earlier callback registrations or shared C dependencies. Input getters and
* result cleanup retain their own effects. Omit this to keep conservative callbacks.
*/
callsJavaScript?: false;
/** Header documentation that `ffi check` watches when reviewing these facts. */
evidence?: Array<MaligatorFfiEvidence>;
/** Facts per parameter, keyed by C name or by 1-based position for unnamed ones. */
params?: Record<string, MaligatorFfiValueFacts>;
returns?: MaligatorFfiValueFacts;
/** Arm caller-storage cleanup after C returns successfully. An omitted success
* condition means every native return acquires cleanup responsibility. A failed
* initialization must leave storage safe to free without calling the destructor.
*/
initializes?: { param: string; success?: string };
/**
* Functions that call a variadic function with fixed argument types, keyed by the
* name each is exported as. The function's own facts apply to every variant.
*/
variants?: Record<string, MaligatorFfiVariant>;
/** Export a runtime selector over these variants. Its first argument is a variant
* export name, followed by that variant's JavaScript arguments.
*/
dispatch?: string;
/**
* Also export the function under this name as one that runs the C call on a worker
* thread and returns a promise of its result. Only for functions the library allows
* on any thread while other calls run. Call-scoped callbacks run on the program's
* thread while C waits; their unhandled errors reject this promise. A destroy
* function keeps its handle closing until the worker retires; conditional cleanup
* failure leaves it open for retry.
*/
async?: string;
}Types: MaligatorFfiEvidence, MaligatorFfiValueFacts, MaligatorFfiVariant
MaligatorFfiFunctionFacts.callsJavaScript
Audited fact that native execution never enters JavaScript, including through earlier callback registrations or shared C dependencies. Input getters and result cleanup retain their own effects. Omit this to keep conservative callbacks.
callsJavaScript?: false;MaligatorFfiFunctionFacts.evidence
Header documentation that ffi check watches when reviewing these facts.
evidence?: Array<MaligatorFfiEvidence>;Types: MaligatorFfiEvidence
MaligatorFfiFunctionFacts.params
Facts per parameter, keyed by C name or by 1-based position for unnamed ones.
params?: Record<string, MaligatorFfiValueFacts>;Types: MaligatorFfiValueFacts
MaligatorFfiFunctionFacts.returns
returns?: MaligatorFfiValueFacts;Types: MaligatorFfiValueFacts
MaligatorFfiFunctionFacts.initializes
Arm caller-storage cleanup after C returns successfully. An omitted success condition means every native return acquires cleanup responsibility. A failed initialization must leave storage safe to free without calling the destructor.
Full TypeScript declaration
initializes?: { param: string; success?: string };MaligatorFfiFunctionFacts.initializes.param
param: string;MaligatorFfiFunctionFacts.initializes.success
success?: stringMaligatorFfiFunctionFacts.variants
Functions that call a variadic function with fixed argument types, keyed by the name each is exported as. The function's own facts apply to every variant.
variants?: Record<string, MaligatorFfiVariant>;Types: MaligatorFfiVariant
MaligatorFfiFunctionFacts.dispatch
Export a runtime selector over these variants. Its first argument is a variant export name, followed by that variant's JavaScript arguments.
dispatch?: string;MaligatorFfiFunctionFacts.async
Also export the function under this name as one that runs the C call on a worker thread and returns a promise of its result. Only for functions the library allows on any thread while other calls run. Call-scoped callbacks run on the program's thread while C waits; their unhandled errors reject this promise. A destroy function keeps its handle closing until the worker retires; conditional cleanup failure leaves it open for retry.
async?: string;MaligatorFfiVariant
One way to call a variadic function: the C types of the arguments after the fixed ones.
Full TypeScript declaration
export interface MaligatorFfiVariant {
/**
* For a variadic function, the C type spellings of the arguments after the fixed
* ones, such as `int` or `const char *`; arguments are named `arg<position>`.
* Variants of other functions have no `args`.
*/
args?: Array<string>;
/**
* Facts for the variadic arguments, keyed by `arg<position>` or by 1-based position.
* Variants of other functions state facts for any parameter, by C name or position,
* replacing the function's own facts for that parameter.
*/
params?: Record<string, MaligatorFfiValueFacts>;
}Types: MaligatorFfiValueFacts
MaligatorFfiVariant.args
For a variadic function, the C type spellings of the arguments after the fixed
ones, such as int or const char *; arguments are named arg<position>.
Variants of other functions have no args.
args?: Array<string>;MaligatorFfiVariant.params
Facts for the variadic arguments, keyed by arg<position> or by 1-based position.
Variants of other functions state facts for any parameter, by C name or position,
replacing the function's own facts for that parameter.
params?: Record<string, MaligatorFfiValueFacts>;Types: MaligatorFfiValueFacts
MaligatorFfiGlobalValueFacts
Representation of a library-owned global, shared by its read and write accessors.
Full TypeScript declaration
export interface MaligatorFfiGlobalValueFacts {
shape?: MaligatorFfiShape;
/** A returned handle stays owned by the library. */
borrowed?: boolean;
callable?: MaligatorFfiCallable;
/** UTF-8 text; a fixed array must contain a NUL within its declared bound. */
string?: true;
/** Fixed array bytes, or a pointer whose byte count is another C global. */
bytes?: true | MaligatorFfiCount;
/** Keep a native copy until replacement or clearing. C must stop retaining the
* previous allocation before either operation. The library's synchronization
* contract still applies to its own readers and mutations.
*/
lifetime?: "replacement";
}Types: MaligatorFfiCount, MaligatorFfiShape, MaligatorFfiCallable
MaligatorFfiGlobalValueFacts.shape
shape?: MaligatorFfiShape;Types: MaligatorFfiShape
MaligatorFfiGlobalValueFacts.borrowed
A returned handle stays owned by the library.
borrowed?: boolean;MaligatorFfiGlobalValueFacts.callable
callable?: MaligatorFfiCallable;Types: MaligatorFfiCallable
MaligatorFfiGlobalValueFacts.string
UTF-8 text; a fixed array must contain a NUL within its declared bound.
string?: true;MaligatorFfiGlobalValueFacts.bytes
Fixed array bytes, or a pointer whose byte count is another C global.
bytes?: true | MaligatorFfiCount;Types: MaligatorFfiCount
MaligatorFfiGlobalValueFacts.lifetime
Keep a native copy until replacement or clearing. C must stop retaining the previous allocation before either operation. The library's synchronization contract still applies to its own readers and mutations.
lifetime?: "replacement";MaligatorFfiGlobalFacts
Explicit access to a library-owned C object. Accessors run on the calling thread.
Full TypeScript declaration
export interface MaligatorFfiGlobalFacts {
/** Export a function that reads the current C value. Pointer results need lifetime facts. */
get?: string;
/** Export a function that assigns a value without retaining JavaScript storage. */
set?: string;
/** Conversion facts; retained pointer copies require an explicit lifetime. */
value?: MaligatorFfiGlobalValueFacts;
/** Header documentation that `ffi check` watches when reviewing these facts. */
evidence?: Array<MaligatorFfiEvidence>;
}MaligatorFfiGlobalFacts.get
Export a function that reads the current C value. Pointer results need lifetime facts.
get?: string;MaligatorFfiGlobalFacts.set
Export a function that assigns a value without retaining JavaScript storage.
set?: string;MaligatorFfiGlobalFacts.value
Conversion facts; retained pointer copies require an explicit lifetime.
value?: MaligatorFfiGlobalValueFacts;Types: MaligatorFfiGlobalValueFacts
MaligatorFfiGlobalFacts.evidence
Header documentation that ffi check watches when reviewing these facts.
evidence?: Array<MaligatorFfiEvidence>;Types: MaligatorFfiEvidence
MaligatorLibraryContract
Facts about a C library that hold wherever it is installed. The binding comes from the headers plus these facts.
Full TypeScript declaration
export interface MaligatorLibraryContract {
/** Headers to bind, spelled as C code includes them, such as `raylib.h` or `curl/curl.h`. */
headers: Array<string>;
/** Discovery alternatives, tried in order. A build config `find` replaces them. */
find?: Array<MaligatorFfiFind>;
/** Facts about types, keyed by typedef or tag. */
types?: Record<string, MaligatorFfiTypeFacts>;
/** Facts about functions, keyed by name. */
functions?: Record<string, MaligatorFfiFunctionFacts>;
/** Getter and setter exports for file-scope C objects, keyed by their C names. */
globals?: Record<string, MaligatorFfiGlobalFacts>;
}Types: MaligatorFfiFind, MaligatorFfiTypeFacts, MaligatorFfiFunctionFacts, MaligatorFfiGlobalFacts
MaligatorLibraryContract.headers
Headers to bind, spelled as C code includes them, such as raylib.h or curl/curl.h.
headers: Array<string>;MaligatorLibraryContract.find
Discovery alternatives, tried in order. A build config find replaces them.
find?: Array<MaligatorFfiFind>;Types: MaligatorFfiFind
MaligatorLibraryContract.types
Facts about types, keyed by typedef or tag.
types?: Record<string, MaligatorFfiTypeFacts>;Types: MaligatorFfiTypeFacts
MaligatorLibraryContract.functions
Facts about functions, keyed by name.
functions?: Record<string, MaligatorFfiFunctionFacts>;Types: MaligatorFfiFunctionFacts
MaligatorLibraryContract.globals
Getter and setter exports for file-scope C objects, keyed by their C names.
globals?: Record<string, MaligatorFfiGlobalFacts>;Types: MaligatorFfiGlobalFacts
defineLibrary
Preserve the inferred contract type. Validation happens when the CLI loads the contract.
export declare function defineLibrary<const Contract extends MaligatorLibraryContract>(
contract: Contract,
): Contract;Types: MaligatorLibraryContract
import { defineLibrary } from "@maligator/cli";
export default defineLibrary({ headers: ["raylib.h"], find: [{ pkgConfig: "raylib" }] });