@gtkx/runtime 1.0.0-rc.4 → 1.1.0

package/src/closure.ts

@@ -0,0 +1,136 @@
+import { type ExternalObject, type Handle, read } from "@gtkx/native";
+import { type AnyClass } from "@gtkx/utils";
+import { bind } from "./bind.js";
+import { boxedT, callbackT, sizedArrayT, structT, uint32T, uint64T, voidT } from "./descriptors.js";
+import { CLOSURE_SIZE, LIB, VALUE_SIZE, VALUE_T } from "./library.js";
+import { getClassType, getHandle, getWrapperClass, instanceClassName, wrapHandle } from "./registry.js";
+import { resolveBoxedType, typeIsA } from "./type.js";
+import { fromValue, getValueType, intoValue } from "./value.js";
+
+/**
+ * Handler backing a `GClosure`. It receives the closure's parameters already converted from their
+ * `GValue`s, and its result is written back into the closure's return `GValue` when it has one.
+ *
+ * A parameter that is itself a `GValue`, such as the target a property binding transform fills in,
+ * arrives as the caller's own `GObject.Value` rather than a copy, so writing to it is how the
+ * handler produces that parameter's value. It stops being valid once the handler returns.
+ */
+type ClosureCallback = (...args: never[]) => unknown;
+
+const CCLOSURE_CALLBACK_OFFSET = CLOSURE_SIZE;
+const N_PARAM_VALUES_INDEX = 2;
+const MARSHAL_DATA_INDEX = 5;
+const CLOSURE_T = boxedT("GClosure", { sharedLibrary: LIB, getTypeFnName: "g_closure_get_type" });
+
+const OWNED_CLOSURE_T = boxedT("GClosure", {
+    ownership: "full",
+    sharedLibrary: LIB,
+    getTypeFnName: "g_closure_get_type",
+});
+
+const MARSHAL_VALUE_T = boxedT("GValue", {
+    sharedLibrary: LIB,
+    getTypeFnName: "g_value_get_type",
+    size: VALUE_SIZE,
+    isCallerAllocated: true,
+});
+
+const MARSHAL_T = callbackT(
+    [
+        CLOSURE_T,
+        MARSHAL_VALUE_T,
+        uint32T,
+        sizedArrayT(MARSHAL_VALUE_T, N_PARAM_VALUES_INDEX, "borrowed", VALUE_SIZE),
+        uint64T,
+        uint64T,
+    ],
+    voidT,
+    {
+        hasUserData: true,
+        userDataIndex: MARSHAL_DATA_INDEX,
+        hasDestroy: true,
+        destroyKind: "closureNotify",
+        scope: "notified",
+    },
+);
+
+const NESTED_VALUE_T = structT("borrowed");
+const gCclosureNew = bind(LIB, "g_cclosure_new", [MARSHAL_T], OWNED_CLOSURE_T);
+const gValueGetBoxed = bind(LIB, "g_value_get_boxed", [VALUE_T], NESTED_VALUE_T);
+const gClosureRef = bind(LIB, "g_closure_ref", [CLOSURE_T], uint64T);
+const gClosureSink = bind(LIB, "g_closure_sink", [CLOSURE_T], voidT);
+const gClosureSetMarshal = bind(LIB, "g_closure_set_marshal", [CLOSURE_T, uint64T], voidT);
+
+const isClosureInstance = (value: object): boolean =>
+    typeIsA(getClassType(value.constructor as AnyClass), resolveBoxedType(CLOSURE_T));
+
+const getNestedValue = (param: ExternalObject<Handle>): object | null =>
+    wrapHandle(gValueGetBoxed(param) as ExternalObject<Handle> | null, getWrapperClass(resolveBoxedType(VALUE_T)));
+
+const fromParamValue = (param: ExternalObject<Handle>): unknown =>
+    getValueType(param) === resolveBoxedType(VALUE_T) ? getNestedValue(param) : fromValue(param);
+
+function describeValue(value: unknown): string {
+    if (value === null) {
+        return "null";
+    }
+
+    if (typeof value !== "object") {
+        return typeof value;
+    }
+
+    return instanceClassName(value);
+}
+
+function marshalFor(callback: ClosureCallback): (...args: unknown[]) => void {
+    return (_closure: unknown, returnValue: unknown, _count: unknown, paramValues: unknown): void => {
+        const values = paramValues as ExternalObject<Handle>[];
+        const args = values.map((value) => fromParamValue(value));
+        const result = (callback as (...values: unknown[]) => unknown)(...(args as never[]));
+
+        if (returnValue !== null) {
+            intoValue(returnValue as ExternalObject<Handle>, result);
+        }
+    };
+}
+
+function newClosure(callback: ClosureCallback): ExternalObject<Handle> {
+    const handle = gCclosureNew(marshalFor(callback)) as ExternalObject<Handle>;
+    const marshal = read(handle, uint64T, CCLOSURE_CALLBACK_OFFSET);
+    gClosureRef(handle);
+    gClosureSink(handle);
+    gClosureSetMarshal(handle, marshal);
+
+    return handle;
+}
+
+/**
+ * Marshals a value passed where a `GObject.Closure` is expected into a closure handle: a function
+ * becomes a new `GClosure` dispatching into it, and an existing closure yields its own handle.
+ * @param value Function to wrap, or an already-built closure.
+ * @throws {ClosureMarshalError} When the value is neither.
+ */
+function toClosure(value: unknown): ExternalObject<Handle> {
+    if (typeof value === "function") {
+        return newClosure(value as ClosureCallback);
+    }
+
+    if (typeof value === "object" && value !== null && isClosureInstance(value)) {
+        return getHandle(value);
+    }
+
+    throw new ClosureMarshalError(`Cannot marshal ${describeValue(value)} into a GObject.Closure`);
+}
+
+/** Same as {@link toClosure}, but passes a null or undefined value through as no closure at all. */
+function tryToClosure(value: unknown): ExternalObject<Handle> | undefined {
+    return value == null ? undefined : toClosure(value);
+}
+
+/** Thrown when a value passed where a `GObject.Closure` is expected cannot be marshalled into one. */
+class ClosureMarshalError extends TypeError {
+    /** Name callers match on when the error is caught as a plain `TypeError`. */
+    public override name = "ClosureMarshalError";
+}
+
+export { type ClosureCallback, ClosureMarshalError, toClosure, tryToClosure };

package/src/default-application.ts

@@ -0,0 +1,21 @@
+import { bind } from "./bind.js";
+import { objectT, voidT } from "./descriptors.js";
+import { GIO_LIB } from "./library.js";
+import { getHandle } from "./registry.js";
+
+const readDefaultApplication = bind(GIO_LIB, "g_application_get_default", [], objectT("borrowed"));
+const writeDefaultApplication = bind(GIO_LIB, "g_application_set_default", [objectT("borrowed")], voidT);
+
+const claimDefaultApplication = (application: object): void => {
+    writeDefaultApplication(getHandle(application));
+};
+
+const releaseDefaultApplication = (application: object): void => {
+    if (readDefaultApplication() !== application) {
+        return;
+    }
+
+    writeDefaultApplication(null);
+};
+
+export { claimDefaultApplication, releaseDefaultApplication };

package/src/descriptors.ts

@@ -1,43 +1,75 @@
 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" }>;
 
+/** 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 = {
@@ -57,11 +89,18 @@ type BoxedOptions = {
     size?: number;
 };
 
-/** How the callee takes a callback's closure, and how long that closure has to stay alive. */
+/**
+ * What the bindings do with a callback's return value, how the callee takes its closure, and how
+ * long that closure has to stay alive.
+ */
 type CallbackOptions = {
-    /** The callee also takes a `GDestroyNotify`, which frees the closure once it is done with it. */
+    /** The callee also takes a destroy notify, which frees the closure once it is done with it. */
     hasDestroy?: boolean;
-    /** Position of the `user_data` argument carrying the closure; without one it can never be freed. */
+    /** 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"];
@@ -71,12 +110,22 @@ type CallbackOptions = {
 type ArrayOptions = {
     /** Stride in bytes between elements stored inline in the array. */
     elementSize?: number | undefined;
+    /** Position of the argument whose buffer a cursor array points into. */
+    baseParamIndex?: 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;
 };
 
+/** Where a cursor array's base buffer and total length come from. */
+type CursorBounds = {
+    /** Position of the argument holding the buffer the cursor points into. */
+    baseParamIndex: number;
+    /** Position of the argument carrying that buffer's element count. */
+    sizeParamIndex: number;
+};
+
 /** 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"`. */
@@ -89,6 +138,12 @@ type FundamentalOptions = {
     isInline?: boolean;
 };
 
+type FundamentalLifecycle = {
+    sharedLibrary: string;
+    refFnName: string;
+    unrefFnName: string;
+};
+
 /** How a plain C struct is stored and wrapped. */
 type StructOptions = {
     /** The caller owns the storage the callee fills, so a decoded value is borrowed instead of copied. */
@@ -101,32 +156,57 @@ type StructOptions = {
     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" };
+const fundamentalLifecycles: Map<string, FundamentalLifecycle> = new Map();
 
+/**
+ * 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,
@@ -138,6 +218,7 @@ 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,
@@ -145,6 +226,7 @@ const enumT = (sharedLibrary: string, typeFnName: string, isSigned: boolean): En
     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,
@@ -182,6 +264,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",
@@ -194,6 +277,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 };
 
@@ -216,6 +300,16 @@ const structT = (ownership: Ownership = "borrowed", options: StructOptions = {})
     return result;
 };
 
+const recordFundamentalLifecycle = (typeName: string, lifecycle: FundamentalLifecycle): void => {
+    if (!fundamentalLifecycles.has(typeName)) {
+        fundamentalLifecycles.set(typeName, lifecycle);
+    }
+};
+
+const fundamentalLifecycleFor = (typeName: string): FundamentalLifecycle | undefined =>
+    fundamentalLifecycles.get(typeName);
+
+/** Builds a descriptor for a fundamental type whose lifetime is managed by named ref and unref functions. */
 const fundamentalT = (
     sharedLibrary: string,
     refFnName: string,
@@ -227,6 +321,7 @@ const fundamentalT = (
 
     if (options.typeName !== undefined) {
         result.typeName = options.typeName;
+        recordFundamentalLifecycle(options.typeName, { sharedLibrary, refFnName, unrefFnName });
     }
 
     if (options.wrapperClass !== undefined) {
@@ -240,6 +335,7 @@ const fundamentalT = (
     return result;
 };
 
+/** Builds a descriptor for an array of items in one of the supported container layouts. */
 const arrayT = (
     itemDescriptor: Descriptor,
     arrayKind: ArrayKind = "array",
@@ -252,6 +348,10 @@ const arrayT = (
         result.elementSize = options.elementSize;
     }
 
+    if (options?.baseParamIndex !== undefined) {
+        result.baseParamIndex = options.baseParamIndex;
+    }
+
     if (options?.sizeParamIndex !== undefined) {
         result.sizeParamIndex = options.sizeParamIndex;
     }
@@ -263,15 +363,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",
@@ -279,9 +383,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,
@@ -289,6 +395,18 @@ const sizedArrayT = (
     elementSize?: number,
 ): ArrayDescriptor => arrayT(itemDescriptor, "sized", ownership, { sizeParamIndex, elementSize });
 
+/**
+ * Builds a descriptor for an out pointer into the buffer another argument supplied, decoded as the
+ * elements from where it points to the end of that buffer.
+ */
+const cursorArrayT = (
+    itemDescriptor: Descriptor,
+    bounds: CursorBounds,
+    ownership: Ownership = "borrowed",
+    elementSize?: number,
+): ArrayDescriptor => arrayT(itemDescriptor, "cursor", ownership, { ...bounds, elementSize });
+
+/** Builds a descriptor for a C array of a fixed length. */
 const fixedArrayT = (
     itemDescriptor: Descriptor,
     fixedSize: number,
@@ -296,6 +414,29 @@ const fixedArrayT = (
     elementSize?: number,
 ): ArrayDescriptor => arrayT(itemDescriptor, "fixed", ownership, { fixedSize, elementSize });
 
+const applyClosureOptions = (result: CallbackDescriptor, options: CallbackOptions): void => {
+    if (options.hasDestroy !== undefined) {
+        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;
+    }
+
+    if (options.scope !== undefined) {
+        result.scope = options.scope;
+    }
+};
+
+/** Builds a descriptor for a function pointer, marshalling a JavaScript function into a native closure. */
 const callbackT = (
     argDescriptors: Descriptor[],
     returnDescriptor: Descriptor,
@@ -303,17 +444,11 @@ const callbackT = (
 ): CallbackDescriptor => {
     const result: CallbackDescriptor = { kind: "callback", argDescriptors, returnDescriptor };
 
-    if (options?.hasDestroy !== undefined) {
-        result.hasDestroy = options.hasDestroy;
+    if (options === undefined) {
+        return result;
     }
 
-    if (options?.userDataIndex !== undefined) {
-        result.userDataIndex = options.userDataIndex;
-    }
-
-    if (options?.scope !== undefined) {
-        result.scope = options.scope;
-    }
+    applyClosureOptions(result, options);
 
     return result;
 };
@@ -344,6 +479,7 @@ export {
     flagsT,
     boxedT,
     structT,
+    fundamentalLifecycleFor,
     fundamentalT,
     arrayT,
     listT,
@@ -353,27 +489,8 @@ export {
     byteArrayT,
     sizedArrayT,
     fixedArrayT,
+    cursorArrayT,
     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,
@@ -381,5 +498,4 @@ export {
     type HashTableDescriptor,
     type CallbackDescriptor,
     type RefDescriptor,
-    type TypeDescriptor,
 };

package/src/error.ts

@@ -18,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;
 };
 

package/src/exit-hook.ts

@@ -1,3 +1,21 @@
 import { quit } from "./lifecycle.js";
 
+const TERMINATION_SIGNALS: NodeJS.Signals[] = ["SIGHUP", "SIGINT", "SIGTERM"];
+
+const isSoleHandler = (signal: NodeJS.Signals): boolean => process.listenerCount(signal) === 1;
+
+const quitOnSignal = (signal: NodeJS.Signals): void => {
+    if (!isSoleHandler(signal)) {
+        return;
+    }
+
+    quit();
+    process.removeAllListeners(signal);
+    process.kill(process.pid, signal);
+};
+
 process.on("exit", quit);
+
+for (const signal of TERMINATION_SIGNALS) {
+    process.on(signal, quitOnSignal);
+}