@gtkx/runtime 1.0.0-rc.3 → 1.0.0

package/src/descriptors.ts

@@ -1,97 +1,192 @@
 import type { ArrayKind, Descriptor, Ownership } from "@gtkx/native";
 import type { AnyClass } from "@gtkx/utils";
 
+/** Descriptor variant for a `gint8`. */
 type Int8Descriptor = Extract<Descriptor, { kind: "int8" }>;
+/** Descriptor variant for a `guint8`. */
 type Uint8Descriptor = Extract<Descriptor, { kind: "uint8" }>;
+/** Descriptor variant for a `gint16`. */
 type Int16Descriptor = Extract<Descriptor, { kind: "int16" }>;
+/** Descriptor variant for a `guint16`. */
 type Uint16Descriptor = Extract<Descriptor, { kind: "uint16" }>;
+/** Descriptor variant for a `gint32`. */
 type Int32Descriptor = Extract<Descriptor, { kind: "int32" }>;
+/** Descriptor variant for a `guint32`. */
 type Uint32Descriptor = Extract<Descriptor, { kind: "uint32" }>;
+/** Descriptor variant for a `gint64` marshalled as a number. */
 type Int64Descriptor = Extract<Descriptor, { kind: "int64" }>;
+/** Descriptor variant for a `guint64` marshalled as a number. */
 type Uint64Descriptor = Extract<Descriptor, { kind: "uint64" }>;
+/** Descriptor variant for a `gint64` marshalled as a bigint. */
 type BigInt64Descriptor = Extract<Descriptor, { kind: "bigint64" }>;
+/** Descriptor variant for a `guint64` marshalled as a bigint. */
 type BigUint64Descriptor = Extract<Descriptor, { kind: "biguint64" }>;
+/** Descriptor variant for a `gfloat`. */
 type Float32Descriptor = Extract<Descriptor, { kind: "float32" }>;
+/** Descriptor variant for a `gdouble`. */
 type Float64Descriptor = Extract<Descriptor, { kind: "float64" }>;
+/** Descriptor variant for an enumeration, carrying the library and `get_type` symbol its GType comes from. */
 type EnumDescriptor = Extract<Descriptor, { kind: "enum" }>;
+/** Descriptor variant for a flags type, carrying the library and `get_type` symbol its GType comes from. */
 type FlagsDescriptor = Extract<Descriptor, { kind: "flags" }>;
+/** Descriptor variant for a `gboolean`. */
 type BooleanDescriptor = Extract<Descriptor, { kind: "boolean" }>;
+/** Descriptor variant for a C string. */
 type StringDescriptor = Extract<Descriptor, { kind: "string" }>;
+/** Descriptor variant for a `GObject`. */
 type ObjectDescriptor = Extract<Descriptor, { kind: "object" }>;
+/** Descriptor variant for a `gunichar`. */
 type UnicharDescriptor = Extract<Descriptor, { kind: "unichar" }>;
+/** Descriptor variant for the absence of a value. */
 type VoidDescriptor = Extract<Descriptor, { kind: "void" }>;
+/** Descriptor variant for an opaque `gpointer`. */
 type BufferDescriptor = Extract<Descriptor, { kind: "buffer" }>;
+/** Descriptor variant for a `GBoxed` value. */
 type BoxedDescriptor = Extract<Descriptor, { kind: "boxed" }>;
-type StructDescriptor = Extract<Descriptor, { kind: "struct" }> & { wrapperClass?: AnyClass };
-type FundamentalDescriptor = Extract<Descriptor, { kind: "fundamental" }> & { wrapperClass?: AnyClass };
+
+/** Descriptor variant for a plain C struct, extended with the class its decoded value is wrapped in. */
+type StructDescriptor = Extract<Descriptor, { kind: "struct" }> & {
+    /** Class a decoded value is wrapped in; without it the wrapper comes from the value's own GType. */
+    wrapperClass?: AnyClass;
+};
+
+/** Descriptor variant for a ref-counted fundamental type, extended with the class its decoded value is wrapped in. */
+type FundamentalDescriptor = Extract<Descriptor, { kind: "fundamental" }> & {
+    /** Class a decoded value is wrapped in; without it the wrapper comes from the type named by `typeName`. */
+    wrapperClass?: AnyClass;
+};
+
+/** Descriptor variant for an array of items in one of the supported container layouts. */
 type ArrayDescriptor = Extract<Descriptor, { kind: "array" }>;
+/** Descriptor variant for a `GHashTable`, marshalled as an array of key/value pairs. */
 type HashTableDescriptor = Extract<Descriptor, { kind: "hashtable" }>;
+/** Descriptor variant for a function pointer a JavaScript function is marshalled into. */
 type CallbackDescriptor = Extract<Descriptor, { kind: "callback" }>;
+/** Descriptor variant for a pointer to another descriptor's value, for an output or inout argument. */
 type RefDescriptor = Extract<Descriptor, { kind: "ref" }>;
-type TypeDescriptor = BigUint64Descriptor & { type: true };
 
+/** Descriptor for a `GType`: a `guint64` marked so it resolves to `G_TYPE_GTYPE` rather than an integer. */
+type TypeDescriptor = BigUint64Descriptor & {
+    /** Distinguishes a GType from a plain `guint64` when the GLib type and the GValue type are resolved. */
+    type: true;
+};
+
+/** How a boxed value is stored, and where its GType and free function are resolved from. */
 type BoxedOptions = {
-    callerAllocated?: boolean;
-    inline?: boolean;
+    /** The caller owns the storage the callee fills, so a decoded value is borrowed instead of copied. */
+    isCallerAllocated?: boolean;
+    /** The value is embedded in the containing struct rather than reached through a pointer. */
+    isInline?: boolean;
+    /** Whether a decoded value is owned by the caller; defaults to `"borrowed"`. */
     ownership?: Ownership;
+    /** Library `getTypeFnName` and `freeFnName` are resolved in. */
     sharedLibrary?: string;
+    /** Symbol returning the boxed GType, used when the type is not already registered under its name. */
     getTypeFnName?: string;
+    /** Symbol that frees the value, for a boxed type with no GType of its own. */
     freeFnName?: string;
+    /** Byte size of the value, needed to copy it into an inline field. */
     size?: number;
 };
 
+/** How the callee takes a callback's closure, and how long that closure has to stay alive. */
 type CallbackOptions = {
+    /** The callee also takes a destroy notify, which frees the closure once it is done with it. */
     hasDestroy?: boolean;
+    /** Signature of that destroy notify; defaults to `destroyNotify`, a one-argument `GDestroyNotify`. */
+    destroyKind?: CallbackDescriptor["destroyKind"];
+    /** The callee also takes a `user_data` pointer; without one the closure can never be freed. */
+    hasUserData?: boolean;
+    /** Position of `user_data` among the callback's own arguments, dropped before the closure is called. */
     userDataIndex?: number;
+    /** Lifetime of the closure; defaults to `notified` when `hasDestroy` is set and `call` otherwise. */
     scope?: CallbackDescriptor["scope"];
 };
 
+/** The lengths and strides a C array layout needs beyond its element type. */
 type ArrayOptions = {
+    /** Stride in bytes between elements stored inline in the array. */
     elementSize?: number | undefined;
+    /** Position of the argument carrying the element count, for a length-bounded array. */
     sizeParamIndex?: number | undefined;
+    /** Element count of a fixed-length array. */
     fixedSize?: number | undefined;
 };
 
+/** How a ref-counted fundamental value is named, wrapped and stored. */
 type FundamentalOptions = {
+    /** Whether a decoded value is owned by the caller; defaults to `"borrowed"`. */
     ownership?: Ownership;
+    /** GLib type name the wrapper class is looked up by. */
     typeName?: string;
+    /** Class a decoded value is wrapped in, instead of the one registered for `typeName`. */
     wrapperClass?: AnyClass;
-    inline?: boolean;
+    /** The value is embedded in the containing struct rather than reached through a pointer. */
+    isInline?: boolean;
 };
 
+/** How a plain C struct is stored and wrapped. */
 type StructOptions = {
-    callerAllocated?: boolean;
-    inline?: boolean;
+    /** The caller owns the storage the callee fills, so a decoded value is borrowed instead of copied. */
+    isCallerAllocated?: boolean;
+    /** The value is embedded in the containing struct rather than reached through a pointer. */
+    isInline?: boolean;
+    /** Byte size of the struct, needed to copy it rather than borrow the pointer. */
     size?: number;
+    /** Class a decoded value is wrapped in, instead of the one registered for its GType. */
     wrapperClass?: AnyClass;
 };
 
+/** Descriptor for a `gint8`, marshalled as a number. */
 const int8T: Int8Descriptor = { kind: "int8" };
+/** Descriptor for a `guint8`, marshalled as a number. */
 const uint8T: Uint8Descriptor = { kind: "uint8" };
+/** Descriptor for a `gint16`, marshalled as a number. */
 const int16T: Int16Descriptor = { kind: "int16" };
+/** Descriptor for a `guint16`, marshalled as a number. */
 const uint16T: Uint16Descriptor = { kind: "uint16" };
+/** Descriptor for a `gint32`, marshalled as a number. */
 const int32T: Int32Descriptor = { kind: "int32" };
+/** Descriptor for a `guint32`, marshalled as a number. */
 const uint32T: Uint32Descriptor = { kind: "uint32" };
+/** Descriptor for a `gint64`, marshalled as a number and rejected outside the 2^53 safe range. */
 const int64T: Int64Descriptor = { kind: "int64" };
+/** Descriptor for a `guint64`, marshalled as a number and rejected outside the 2^53 safe range. */
 const uint64T: Uint64Descriptor = { kind: "uint64" };
+/** Descriptor for a `gint64`, marshalled as a bigint so the full 64-bit range survives. */
 const bigint64T: BigInt64Descriptor = { kind: "bigint64" };
+/** Descriptor for a `guint64`, marshalled as a bigint so the full 64-bit range survives. */
 const biguint64T: BigUint64Descriptor = { kind: "biguint64" };
+/** Descriptor for a `GType`, marshalled as a bigint and recognized as a GType by GValue conversion. */
 const gtypeT: TypeDescriptor = { kind: "biguint64", type: true };
+/** Descriptor for a `gfloat`. */
 const float32T: Float32Descriptor = { kind: "float32" };
+/** Descriptor for a `gdouble`. */
 const float64T: Float64Descriptor = { kind: "float64" };
+/** Descriptor for a `gboolean`, marshalled as a JavaScript boolean. */
 const booleanT: BooleanDescriptor = { kind: "boolean" };
+/** Descriptor for the absence of a value, used as the return descriptor of a `void` function. */
 const voidT: VoidDescriptor = { kind: "void" };
+/** Descriptor for a `gunichar`, marshalled as a single-character string or a codepoint number. */
 const unicharT: UnicharDescriptor = { kind: "unichar" };
+/** Descriptor for an opaque `gpointer`, taken from a typed array's memory or a numeric address. */
 const bufferT: BufferDescriptor = { kind: "buffer" };
 
+/**
+ * Builds a descriptor for a C string, whose optional length sizes the caller-allocated buffer
+ * used when the string is passed by reference.
+ */
 const stringT = (ownership: Ownership = "borrowed", length?: number): StringDescriptor =>
     length === undefined ? { kind: "string", ownership } : { kind: "string", ownership, length };
 
+/** Builds a descriptor for a `GObject`, wrapped in the class registered for its runtime GType. */
 const objectT = (ownership: Ownership = "borrowed"): ObjectDescriptor => ({ kind: "object", ownership });
 
+/** Wraps a descriptor in a pointer to it, for an output or inout argument. */
 const refT = (innerDescriptor: Descriptor, isInout = false): RefDescriptor =>
     isInout ? { kind: "ref", innerDescriptor, inout: true } : { kind: "ref", innerDescriptor };
 
+/** Builds a descriptor for a `GHashTable`, marshalled as an array of key/value pairs. */
 const hashTableT = (
     keyDescriptor: Descriptor,
     valueDescriptor: Descriptor,
@@ -103,18 +198,20 @@ const hashTableT = (
     ownership,
 });
 
+/** Builds a descriptor for an enumeration, resolving its GType from the named `get_type` function. */
 const enumT = (sharedLibrary: string, typeFnName: string, isSigned: boolean): EnumDescriptor => ({
     kind: "enum",
     sharedLibrary,
     getTypeFnName: typeFnName,
-    signed: isSigned,
+    isSigned,
 });
 
+/** Builds a descriptor for a flags type, resolving its GType from the named `get_type` function. */
 const flagsT = (sharedLibrary: string, typeFnName: string, isSigned: boolean): FlagsDescriptor => ({
     kind: "flags",
     sharedLibrary,
     getTypeFnName: typeFnName,
-    signed: isSigned,
+    isSigned,
 });
 
 const applyBoxedNames = (result: BoxedDescriptor, options: BoxedOptions): void => {
@@ -134,12 +231,12 @@ const applyBoxedNames = (result: BoxedDescriptor, options: BoxedOptions): void =
 const applyBoxedOptions = (result: BoxedDescriptor, options: BoxedOptions): void => {
     applyBoxedNames(result, options);
 
-    if (options.callerAllocated) {
-        result.callerAllocated = true;
+    if (options.isCallerAllocated) {
+        result.isCallerAllocated = true;
     }
 
-    if (options.inline) {
-        result.inline = true;
+    if (options.isInline) {
+        result.isInline = true;
     }
 
     if (options.size !== undefined) {
@@ -147,6 +244,7 @@ const applyBoxedOptions = (result: BoxedDescriptor, options: BoxedOptions): void
     }
 };
 
+/** Builds a descriptor for a `GBoxed` value of the named type. */
 const boxedT = (typeName: string, options: BoxedOptions = {}): BoxedDescriptor => {
     const result: BoxedDescriptor = {
         kind: "boxed",
@@ -159,6 +257,7 @@ const boxedT = (typeName: string, options: BoxedOptions = {}): BoxedDescriptor =
     return result;
 };
 
+/** Builds a descriptor for a plain C struct. */
 const structT = (ownership: Ownership = "borrowed", options: StructOptions = {}): StructDescriptor => {
     const result: StructDescriptor = { kind: "struct", ownership };
 
@@ -170,17 +269,18 @@ const structT = (ownership: Ownership = "borrowed", options: StructOptions = {})
         result.wrapperClass = options.wrapperClass;
     }
 
-    if (options.callerAllocated) {
-        result.callerAllocated = true;
+    if (options.isCallerAllocated) {
+        result.isCallerAllocated = true;
     }
 
-    if (options.inline) {
-        result.inline = true;
+    if (options.isInline) {
+        result.isInline = true;
     }
 
     return result;
 };
 
+/** Builds a descriptor for a fundamental type whose lifetime is managed by named ref and unref functions. */
 const fundamentalT = (
     sharedLibrary: string,
     refFnName: string,
@@ -198,13 +298,14 @@ const fundamentalT = (
         result.wrapperClass = options.wrapperClass;
     }
 
-    if (options.inline) {
-        result.inline = true;
+    if (options.isInline) {
+        result.isInline = true;
     }
 
     return result;
 };
 
+/** Builds a descriptor for an array of items in one of the supported container layouts. */
 const arrayT = (
     itemDescriptor: Descriptor,
     arrayKind: ArrayKind = "array",
@@ -228,15 +329,19 @@ const arrayT = (
     return result;
 };
 
+/** Builds a descriptor for a `GList` of items. */
 const listT = (itemDescriptor: Descriptor, ownership: Ownership = "borrowed"): ArrayDescriptor =>
     arrayT(itemDescriptor, "glist", ownership);
 
+/** Builds a descriptor for a `GSList` of items. */
 const slistT = (itemDescriptor: Descriptor, ownership: Ownership = "borrowed"): ArrayDescriptor =>
     arrayT(itemDescriptor, "gslist", ownership);
 
+/** Builds a descriptor for a `GPtrArray` of items. */
 const ptrArrayT = (itemDescriptor: Descriptor, ownership: Ownership = "borrowed"): ArrayDescriptor =>
     arrayT(itemDescriptor, "gptrarray", ownership);
 
+/** Builds a descriptor for a `GArray` of items, optionally with an explicit element size. */
 const gArrayT = (
     itemDescriptor: Descriptor,
     ownership: Ownership = "borrowed",
@@ -244,9 +349,11 @@ const gArrayT = (
 ): ArrayDescriptor =>
     arrayT(itemDescriptor, "garray", ownership, elementSize === undefined ? undefined : { elementSize });
 
+/** Builds a descriptor for a `GByteArray`. */
 const byteArrayT = (ownership: Ownership = "borrowed"): ArrayDescriptor =>
     arrayT(uint8T, "gbytearray", ownership);
 
+/** Builds a descriptor for a C array whose length is carried by another argument. */
 const sizedArrayT = (
     itemDescriptor: Descriptor,
     sizeParamIndex: number,
@@ -254,6 +361,7 @@ const sizedArrayT = (
     elementSize?: number,
 ): ArrayDescriptor => arrayT(itemDescriptor, "sized", ownership, { sizeParamIndex, elementSize });
 
+/** Builds a descriptor for a C array of a fixed length. */
 const fixedArrayT = (
     itemDescriptor: Descriptor,
     fixedSize: number,
@@ -261,6 +369,7 @@ const fixedArrayT = (
     elementSize?: number,
 ): ArrayDescriptor => arrayT(itemDescriptor, "fixed", ownership, { fixedSize, elementSize });
 
+/** Builds a descriptor for a function pointer, marshalling a JavaScript function into a native closure. */
 const callbackT = (
     argDescriptors: Descriptor[],
     returnDescriptor: Descriptor,
@@ -272,6 +381,14 @@ const callbackT = (
         result.hasDestroy = options.hasDestroy;
     }
 
+    if (options?.destroyKind !== undefined) {
+        result.destroyKind = options.destroyKind;
+    }
+
+    if (options?.hasUserData !== undefined) {
+        result.hasUserData = options.hasUserData;
+    }
+
     if (options?.userDataIndex !== undefined) {
         result.userDataIndex = options.userDataIndex;
     }
@@ -319,26 +436,6 @@ export {
     sizedArrayT,
     fixedArrayT,
     callbackT,
-    type Int8Descriptor,
-    type Uint8Descriptor,
-    type Int16Descriptor,
-    type Uint16Descriptor,
-    type Int32Descriptor,
-    type Uint32Descriptor,
-    type Int64Descriptor,
-    type Uint64Descriptor,
-    type BigInt64Descriptor,
-    type BigUint64Descriptor,
-    type Float32Descriptor,
-    type Float64Descriptor,
-    type EnumDescriptor,
-    type FlagsDescriptor,
-    type BooleanDescriptor,
-    type StringDescriptor,
-    type ObjectDescriptor,
-    type UnicharDescriptor,
-    type VoidDescriptor,
-    type BufferDescriptor,
     type BoxedDescriptor,
     type StructDescriptor,
     type FundamentalDescriptor,
@@ -346,5 +443,4 @@ export {
     type HashTableDescriptor,
     type CallbackDescriptor,
     type RefDescriptor,
-    type TypeDescriptor,
 };

package/src/error.ts

@@ -2,8 +2,14 @@ import type { ExternalObject, Handle, Ref } from "@gtkx/native";
 import { getWrapperClass, wrapHandle } from "./registry.js";
 import { getErrorType, isTypedClass } from "./type.js";
 
+/**
+ * A wrapped `GError` thrown across the FFI boundary: a JavaScript `Error` that also identifies its
+ * GLib domain and code.
+ */
 type ErrorLike = Error & {
+    /** Quark of the error domain the code belongs to. */
     domain: number;
+    /** Error code, meaningful only within `ErrorLike.domain`. */
     code: number;
 };
 
@@ -12,6 +18,7 @@ type ErrorLike = Error & {
  * matches wrapped GLib errors belonging to a specific error domain.
  */
 type ErrorDomain<T extends Record<string, number>> = T & {
+    /** Backs `instanceof`, matching a wrapped GLib error whose domain is this one. */
     [Symbol.hasInstance]: (value: unknown) => value is ErrorLike;
 };
 
@@ -21,7 +28,7 @@ function checkError(error: Ref): void {
     }
 
     const gerror = wrapHandle(error.value as ExternalObject<Handle>, getWrapperClass(getErrorType())) as ErrorLike;
-    const callSite = new Error("gtkx call site");
+    const callSite = new Error("GTKX call site");
     const callerFrames = (callSite.stack ?? "").split("\n").slice(2);
     gerror.stack = [`${gerror.name}: ${gerror.message}`, ...callerFrames].join("\n");
     throw gerror;

package/src/fn.ts

@@ -1,6 +1,7 @@
-import type { Descriptor, Ref } from "@gtkx/native";
-import { type Arg, isCallerAllocatedArg, isInoutArg, isOutputArg, isRefArg } from "./arg.js";
-import { bind } from "./bind.js";
+import type { CallDescriptor, Descriptor, ExternalObject, Ref } from "@gtkx/native";
+import { call, bind as nativeBind } from "@gtkx/native";
+import type { RefSeeds } from "./vfunc-seeds.js";
+import { type Arg, isCallerAllocatedArg, isOutputArg, isRefArg, requiresInputArg } from "./arg.js";
 import { wrapCallbackValue } from "./callback.js";
 import { boxedT, refT } from "./descriptors.js";
 import { checkError } from "./error.js";
@@ -9,24 +10,37 @@ import { fromNative } from "./native-value.js";
 import { getHandle } from "./registry.js";
 import { packTupleResult } from "./tuple.js";
 
+/** The signature a native function is bound against. */
 type FnSpec = {
+    /** The C arguments in declaration order, including the ones the callee writes into. */
     args: Arg[];
+    /** Descriptor for the C return value, packed first when output arguments are also returned. */
     returns: Descriptor;
-    throws?: boolean;
+    /** The function takes a trailing `GError**`, whose contents are thrown as an error on return. */
+    canThrow?: boolean;
+    /**
+     * How many of `args` precede the callee's ellipsis, marking it variadic. Omitting it binds a
+     * fixed-arity call, which passes the wrong argument classes to a variadic callee on some
+     * architectures.
+     */
+    fixedArgCount?: number;
 };
 
 type ArgSpec = {
     arg: Arg;
+    index: number;
     isRef: boolean;
     isCallerAllocated: boolean;
-    consumesInput: boolean;
+    requiresInput: boolean;
     inputIndex: number;
     isOutParam: boolean;
 };
 
+const NO_OUT_PARAMS: unknown[] = [];
+
 const buildNativeArgTypes = (args: Arg[], canThrow: boolean): Descriptor[] => {
     const nativeArgTypes = args.map((argSpec) =>
-        argSpec.direction !== undefined && argSpec.callerAllocated !== true ? refT(argSpec.type) : argSpec.type,
+        argSpec.direction !== undefined && argSpec.isCallerAllocated !== true ? refT(argSpec.type) : argSpec.type,
     );
 
     if (canThrow) {
@@ -41,17 +55,18 @@ const buildNativeArgTypes = (args: Arg[], canThrow: boolean): Descriptor[] => {
 const buildArgSpecs = (args: Arg[]): ArgSpec[] => {
     let inputCursor = 0;
 
-    return args.map((arg) => {
+    return args.map((arg, index) => {
         const isRef = isRefArg(arg);
-        const isConsumesInput = !isRef || isInoutArg(arg);
-        const isOutParam = isOutputArg(arg) && arg.consumed !== true;
+        const requiresInput = requiresInputArg(arg);
+        const isOutParam = isOutputArg(arg) && arg.isConsumed !== true;
 
         return {
             arg,
+            index,
             isRef,
             isCallerAllocated: isCallerAllocatedArg(arg),
-            consumesInput: isConsumesInput,
-            inputIndex: isConsumesInput ? inputCursor++ : -1,
+            requiresInput,
+            inputIndex: requiresInput ? inputCursor++ : -1,
             isOutParam,
         };
     });
@@ -63,19 +78,19 @@ const resolveCallerAllocated = (inputs: unknown[], inputIndex: number): unknown
     return wrapper == null ? wrapper : getHandle(wrapper);
 };
 
-const buildRefValue = (isInputConsumed: boolean, inputs: unknown[], inputIndex: number): Ref => ({
-    value: isInputConsumed ? inputs[inputIndex] : null,
+const buildRefValue = (spec: ArgSpec, inputs: unknown[], seeds: RefSeeds | undefined): Ref => ({
+    value: spec.requiresInput ? inputs[spec.inputIndex] : (seeds?.get(spec.index) ?? null),
 });
 
-const buildNativeValue = (spec: ArgSpec, inputs: unknown[]): unknown => {
-    const { arg, isRef, isCallerAllocated, consumesInput, inputIndex } = spec;
+const buildNativeValue = (spec: ArgSpec, inputs: unknown[], seeds: RefSeeds | undefined): unknown => {
+    const { arg, isRef, isCallerAllocated, inputIndex } = spec;
 
     if (isCallerAllocated) {
         return resolveCallerAllocated(inputs, inputIndex);
     }
 
     if (isRef) {
-        return buildRefValue(consumesInput, inputs, inputIndex);
+        return buildRefValue(spec, inputs, seeds);
     }
 
     if (arg.type.kind === "callback") {
@@ -85,44 +100,79 @@ const buildNativeValue = (spec: ArgSpec, inputs: unknown[]): unknown => {
     return inputs[inputIndex];
 };
 
-const buildNativeValues = (plans: ArgSpec[], inputs: unknown[]): unknown[] =>
-    plans.map((plan) => buildNativeValue(plan, inputs));
+const buildNativeValues = (plans: ArgSpec[], inputs: unknown[], seeds: RefSeeds | undefined): unknown[] =>
+    plans.map((plan) => buildNativeValue(plan, inputs, seeds));
+
+const readOutParams = (outPlans: ArgSpec[], inputs: unknown[], nativeValues: unknown[]): unknown[] => {
+    if (outPlans.length === 0) {
+        return NO_OUT_PARAMS;
+    }
 
-const readOutParams = (plans: ArgSpec[], inputs: unknown[], nativeValues: unknown[]): unknown[] => {
-    const outParams: unknown[] = [];
+    return Array.from(outPlans, (plan) =>
+        plan.isCallerAllocated
+            ? inputs[plan.inputIndex]
+            : fromNative(plan.arg.type, (nativeValues[plan.index] as Ref).value));
+};
 
-    for (const [index, { arg, isCallerAllocated, inputIndex, isOutParam }] of plans.entries()) {
-        if (!isOutParam) {
-            continue;
-        }
+const isPassThroughPlan = (plan: ArgSpec, index: number): boolean =>
+    plan.inputIndex === index &&
+    !plan.isRef &&
+    !plan.isCallerAllocated &&
+    plan.arg.type.kind !== "callback";
 
-        outParams.push(
-            isCallerAllocated ? inputs[inputIndex] : fromNative(arg.type, (nativeValues[index] as Ref).value),
-        );
+const resizeInputs = (inputs: unknown[], argCount: number): unknown[] => {
+    while (inputs.length < argCount) {
+        inputs.push(undefined);
     }
 
-    return outParams;
+    if (inputs.length > argCount) {
+        inputs.length = argCount;
+    }
+
+    return inputs;
 };
 
-function fn(sharedLibrary: string, symbol: string, spec: FnSpec): (...inputs: unknown[]) => unknown {
-    const { args, returns: returnDescriptor, throws = false } = spec;
-    const nativeArgTypes = buildNativeArgTypes(args, throws);
-    const nativeFn = bind(sharedLibrary, symbol, nativeArgTypes, returnDescriptor);
+const directCallable = (
+    descriptor: ExternalObject<CallDescriptor>,
+    returnDescriptor: Descriptor,
+    argCount: number,
+): ((...inputs: unknown[]) => unknown) => {
+    if (returnDescriptor.kind === "void") {
+        return (...inputs) => {
+            call(descriptor, resizeInputs(inputs, argCount));
+        };
+    }
+
+    return (...inputs) => fromNative(returnDescriptor, call(descriptor, resizeInputs(inputs, argCount)));
+};
+
+function fromNativeCallable(
+    descriptor: ExternalObject<CallDescriptor>,
+    spec: FnSpec,
+    getRefSeeds?: () => RefSeeds | undefined,
+): (...inputs: unknown[]) => unknown {
+    const { args, returns: returnDescriptor, canThrow = false } = spec;
     const hasPrimary = returnDescriptor.kind !== "void";
     const plans = buildArgSpecs(args);
+    const outPlans = plans.filter((plan) => plan.isOutParam);
+    const arePassThrough = plans.every((plan, index) => isPassThroughPlan(plan, index));
+
+    if (!canThrow && arePassThrough) {
+        return directCallable(descriptor, returnDescriptor, plans.length);
+    }
 
     const shape = (inputs: unknown[], nativeValues: unknown[], nativeResult: unknown): unknown => {
         const primary = hasPrimary ? fromNative(returnDescriptor, nativeResult) : undefined;
 
-        return packTupleResult(readOutParams(plans, inputs, nativeValues), primary, hasPrimary);
+        return packTupleResult(readOutParams(outPlans, inputs, nativeValues), primary, hasPrimary);
     };
 
-    if (throws) {
+    if (canThrow) {
         return (...inputs) => {
-            const nativeValues = buildNativeValues(plans, inputs);
+            const nativeValues = buildNativeValues(plans, inputs, getRefSeeds?.());
             const errorRef: Ref = { value: null };
             nativeValues.push(errorRef);
-            const nativeResult = nativeFn(...nativeValues);
+            const nativeResult = call(descriptor, nativeValues);
             checkError(errorRef);
 
             return shape(inputs, nativeValues, nativeResult);
@@ -130,10 +180,25 @@ function fn(sharedLibrary: string, symbol: string, spec: FnSpec): (...inputs: un
     }
 
     return (...inputs) => {
-        const nativeValues = buildNativeValues(plans, inputs);
+        const nativeValues = buildNativeValues(plans, inputs, getRefSeeds?.());
 
-        return shape(inputs, nativeValues, nativeFn(...nativeValues));
+        return shape(inputs, nativeValues, call(descriptor, nativeValues));
     };
 }
 
-export { fn };
+/**
+ * Binds a symbol in a shared library to a callable that marshals its inputs and packs output
+ * arguments into the result. When the spec sets `canThrow`, the reported `GError` is thrown.
+ *
+ * @param sharedLibrary Shared library the symbol is looked up in.
+ * @param symbol Name of the C symbol to bind.
+ * @param spec Argument and return descriptors the call is marshalled through.
+ */
+function fn(sharedLibrary: string, symbol: string, spec: FnSpec): (...inputs: unknown[]) => unknown {
+    const nativeArgTypes = buildNativeArgTypes(spec.args, spec.canThrow ?? false);
+    const descriptor = nativeBind(sharedLibrary, symbol, nativeArgTypes, spec.returns, spec.fixedArgCount);
+
+    return fromNativeCallable(descriptor, spec);
+}
+
+export { buildNativeArgTypes, fn, fromNativeCallable };