dlopen

function dlopen<Fns extends Record<string, FFIFunction>>(
  libName: string,
  defs: Fns,
): Library<Fns>;

import { dlopen, FFIType } from 'arkffi';

const lib = dlopen('libffi_target.so', {
  add:     { args: [FFIType.double, FFIType.double],     returns: FFIType.double },
  compute: { args: [FFIType.int32, FFIType.double, FFIType.CString], returns: FFIType.double },
});

lib.symbols.add(2.0, 3.0);
lib.symbols.compute(0, 4.0, 'square');
lib.close();

interface FFIFunction {
  args: (string | StructSchema)[];  // Parameter type codes, supports StructSchema
  returns: string | StructSchema;   // Return type code, supports StructSchema
  threadsafe?: boolean;             // For JSCallback definitions
}

const Complex = Struct({ real: FFIType.double, imag: FFIType.double });

const lib = dlopen('libfft.so', {
  complex_add: {
    args: [Complex, Complex],   // expands to 4 doubles
    returns: Complex,            // encodes as '2' → returns buffer pointer
  },
});

let a = Complex.create({ real: 1, imag: 2 });
let b = Complex.create({ real: 3, imag: 4 });
let ptr: number = lib.symbols.complex_add(a, b);
let result = Complex.fromPtr(ptr);
console.log(result.real, result.imag); // 4, 6

defineFunction(handle, 'complex_add', 'dddd', '2')
                           ↑ StructSchema expanded to field types
At call time:
  ArrayBuffer → unpacked as [1, 2, 3, 4] → NAPI
  NAPI returns buffer → ffi.ptr(buf) → pointer returned to user

const Complex = Struct({ real: FFIType.double, imag: FFIType.double });
const lib = dlopen('libfft.so', {
  complex_mul: { args: [Complex, Complex], returns: Complex },
});

let a = Complex.create({ real: 4, imag: 1 });
let b = Complex.create({ real: 3, imag: 3 });
lib.symbols.complex_mul.async(a, b).then((ptr: number) => {
  let result = Complex.fromPtr(ptr);
  releasePtr(ptr);
});

const lib = dlopen('lib.so', {
  add: { args: [FFIType.double, FFIType.double], returns: FFIType.double },
});
lib.symbols.add.async(2.0, 3.0).then((r: number) => console.log(r));

const lib = dlopen('lib.so', {
  myFunc: { args: [FFIType.double, FFIType.double], returns: FFIType.double },
});
lib.symbols.myFunc(2.0, 3.0); // autocompleted