@gtkx/runtime 1.2.2 → 1.4.0

package/src/fn.ts

@@ -1,14 +1,16 @@
-import type { CallDescriptor, Descriptor, ExternalObject, Ref } from "@gtkx/native";
+import type { CallDescriptor, Descriptor, ExternalObject, Handle, 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 { type Arg, isCallerAllocatedArg, isOutputArg, isRefArg, isUnpackedArg, requiresInputArg } from "./arg.js";
 import { wrapCallbackValue } from "./callback.js";
-import { boxedT, refT } from "./descriptors.js";
+import { boxedT, isGtypeDescriptor, refT } from "./descriptors.js";
 import { checkError } from "./error.js";
 import { LIB } from "./library.js";
-import { fromNative } from "./native-value.js";
+import { fromNative, toNative } from "./native-value.js";
 import { getHandle } from "./registry.js";
 import { hasSurfacedPrimary, packTupleResult } from "./tuple.js";
+import { TYPE_INVALID } from "./type.js";
+import { fromValue, getValueType } from "./value.js";
 
 /** The signature a native function is bound against. */
 type FnSpec = {
@@ -29,6 +31,8 @@ type FnSpec = {
      * architectures.
      */
     fixedArgCount?: number;
+    /** The callee returns a `GValue`, surfaced as what it holds rather than as the value itself. */
+    isReturnUnpacked?: boolean;
 };
 
 type ArgSpec = {
@@ -36,13 +40,18 @@ type ArgSpec = {
     index: number;
     isRef: boolean;
     isCallerAllocated: boolean;
+    isUnpacked: boolean;
     requiresInput: boolean;
     inputIndex: number;
     isOutParam: boolean;
+    carriesGtype: boolean;
 };
 
 const NO_OUT_PARAMS: unknown[] = [];
 
+const hasGtypeInput = (descriptor: Descriptor): boolean =>
+    isGtypeDescriptor(descriptor) || (descriptor.kind === "array" && isGtypeDescriptor(descriptor.itemDescriptor));
+
 const buildNativeArgTypes = (args: Arg[], canThrow: boolean): Descriptor[] => {
     const nativeArgTypes = args.map((argSpec) =>
         argSpec.direction !== undefined && argSpec.isCallerAllocated !== true ? refT(argSpec.type) : argSpec.type,
@@ -70,9 +79,11 @@ const buildArgSpecs = (args: Arg[]): ArgSpec[] => {
             index,
             isRef,
             isCallerAllocated: isCallerAllocatedArg(arg),
+            isUnpacked: isUnpackedArg(arg),
             requiresInput,
             inputIndex: requiresInput ? inputCursor++ : -1,
             isOutParam,
+            carriesGtype: hasGtypeInput(arg.type),
         };
     });
 };
@@ -83,8 +94,11 @@ const resolveCallerAllocated = (inputs: unknown[], inputIndex: number): unknown
     return wrapper == null ? wrapper : getHandle(wrapper);
 };
 
+const inputValueFor = (spec: ArgSpec, inputs: unknown[]): unknown =>
+    spec.carriesGtype ? toNative(spec.arg.type, inputs[spec.inputIndex]) : inputs[spec.inputIndex];
+
 const buildRefValue = (spec: ArgSpec, inputs: unknown[], seeds: RefSeeds | undefined): Ref => ({
-    value: spec.requiresInput ? inputs[spec.inputIndex] : (seeds?.get(spec.index) ?? null),
+    value: spec.requiresInput ? inputValueFor(spec, inputs) : (seeds?.get(spec.index) ?? null),
 });
 
 const buildNativeValue = (spec: ArgSpec, inputs: unknown[], seeds: RefSeeds | undefined): unknown => {
@@ -102,12 +116,30 @@ const buildNativeValue = (spec: ArgSpec, inputs: unknown[], seeds: RefSeeds | un
         return wrapCallbackValue(arg.type, inputs[inputIndex]);
     }
 
-    return inputs[inputIndex];
+    return inputValueFor(spec, inputs);
 };
 
 const buildNativeValues = (plans: ArgSpec[], inputs: unknown[], seeds: RefSeeds | undefined): unknown[] =>
     plans.map((plan) => buildNativeValue(plan, inputs, seeds));
 
+const unpackValueHandle = (handle: ExternalObject<Handle> | null): unknown => {
+    if (handle === null || getValueType(handle) === TYPE_INVALID) {
+        return null;
+    }
+
+    return fromValue(handle);
+};
+
+const readCallerAllocated = (plan: ArgSpec, inputs: unknown[]): unknown => {
+    const wrapper = inputs[plan.inputIndex];
+
+    if (!plan.isUnpacked) {
+        return wrapper;
+    }
+
+    return unpackValueHandle(wrapper == null ? null : getHandle(wrapper));
+};
+
 const readOutParams = (outPlans: ArgSpec[], inputs: unknown[], nativeValues: unknown[]): unknown[] => {
     if (outPlans.length === 0) {
         return NO_OUT_PARAMS;
@@ -115,7 +147,7 @@ const readOutParams = (outPlans: ArgSpec[], inputs: unknown[], nativeValues: unk
 
     return Array.from(outPlans, (plan) =>
         plan.isCallerAllocated
-            ? inputs[plan.inputIndex]
+            ? readCallerAllocated(plan, inputs)
             : fromNative(plan.arg.type, (nativeValues[plan.index] as Ref).value));
 };
 
@@ -123,8 +155,20 @@ const isPassThroughPlan = (plan: ArgSpec, index: number): boolean =>
     plan.inputIndex === index &&
     !plan.isRef &&
     !plan.isCallerAllocated &&
+    !plan.carriesGtype &&
     plan.arg.type.kind !== "callback";
 
+const requiredInputIndices = (plans: ArgSpec[]): number[] =>
+    plans.filter((plan) => plan.requiresInput && plan.arg.isRequired === true).map((plan) => plan.inputIndex);
+
+const assertRequiredInputs = (requiredIndices: number[], inputs: unknown[]): void => {
+    for (const index of requiredIndices) {
+        if (inputs[index] === undefined) {
+            throw new TypeError(`Missing required argument at position ${String(index + 1)}`);
+        }
+    }
+};
+
 const resizeInputs = (inputs: unknown[], argCount: number): unknown[] => {
     while (inputs.length < argCount) {
         inputs.push(undefined);
@@ -137,14 +181,25 @@ const resizeInputs = (inputs: unknown[], argCount: number): unknown[] => {
     return inputs;
 };
 
+const returnReader = (spec: FnSpec): ((nativeResult: unknown) => unknown) =>
+    spec.isReturnUnpacked === true
+        ? (nativeResult) => unpackValueHandle((nativeResult ?? null) as ExternalObject<Handle> | null)
+        : (nativeResult) => fromNative(spec.returns, nativeResult);
+
 const directCallable = (
     descriptor: ExternalObject<CallDescriptor>,
-    returnDescriptor: Descriptor,
+    readReturn: (nativeResult: unknown) => unknown,
     hasPrimary: boolean,
-    argCount: number,
+    plans: ArgSpec[],
 ): ((...inputs: unknown[]) => unknown) => {
-    const marshal = (inputs: unknown[]): unknown =>
-        fromNative(returnDescriptor, call(descriptor, resizeInputs(inputs, argCount)));
+    const argCount = plans.length;
+    const requiredIndices = requiredInputIndices(plans);
+
+    const marshal = (inputs: unknown[]): unknown => {
+        assertRequiredInputs(requiredIndices, inputs);
+
+        return readReturn(call(descriptor, resizeInputs(inputs, argCount)));
+    };
 
     if (hasPrimary) {
         return (...inputs) => marshal(inputs);
@@ -165,20 +220,20 @@ function fromNativeCallable(
     const plans = buildArgSpecs(args);
     const outPlans = plans.filter((plan) => plan.isOutParam);
     const arePassThrough = plans.every((plan, index) => isPassThroughPlan(plan, index));
+    const readReturn = returnReader(spec);
 
     if (!canThrow && arePassThrough) {
-        return directCallable(descriptor, returnDescriptor, hasPrimary, plans.length);
+        return directCallable(descriptor, readReturn, hasPrimary, plans);
     }
 
+    const requiredIndices = requiredInputIndices(plans);
+
     const shape = (inputs: unknown[], nativeValues: unknown[], nativeResult: unknown): unknown =>
-        packTupleResult(
-            readOutParams(outPlans, inputs, nativeValues),
-            fromNative(returnDescriptor, nativeResult),
-            hasPrimary,
-        );
+        packTupleResult(readOutParams(outPlans, inputs, nativeValues), readReturn(nativeResult), hasPrimary);
 
     if (canThrow) {
         return (...inputs) => {
+            assertRequiredInputs(requiredIndices, inputs);
             const nativeValues = buildNativeValues(plans, inputs, getRefSeeds?.());
             const errorRef: Ref = { value: null };
             nativeValues.push(errorRef);
@@ -190,6 +245,7 @@ function fromNativeCallable(
     }
 
     return (...inputs) => {
+        assertRequiredInputs(requiredIndices, inputs);
         const nativeValues = buildNativeValues(plans, inputs, getRefSeeds?.());
 
         return shape(inputs, nativeValues, call(descriptor, nativeValues));

package/src/index.ts

@@ -7,6 +7,8 @@ export { type ClosureCallback, ClosureMarshalError, toClosure, tryToClosure } fr
 /** @public */
 export { createErrorDomain, type ErrorDomain } from "./error.js";
 /** @public */
+export { type Field, type StridedField } from "./field.js";
+/** @public */
 export { onExit, quit, quitApplication, runApplication, type RunApplicationResult } from "./lifecycle.js";
 /** @public */
 export { offSignal, onceSignal, onSignal } from "./listeners.js";
@@ -24,23 +26,45 @@ export {
     setObjectProperty,
 } from "./object.js";
 /** @public */
-export { promisify } from "./promisify.js";
+export { getParamSpecFlags, getParamSpecOwnerType, getParamSpecValueType } from "./param-spec.js";
+/** @public */
+export { promisify, trimFinish } from "./promisify.js";
+/** @public */
+export {
+    coerceObjectProperty,
+    getDeclaredPropertyName,
+    isReadableProperty,
+    newParamSpecOverride,
+} from "./properties.js";
+/** @public */
+export { matchAllRegex, matchRegex } from "./regex.js";
 /** @public */
-export { type Interface, registerClass } from "./register-class.js";
+export { type Interface, registerClass, type SignalGType, type SignalSpec } from "./register-class.js";
 /** @public */
 export {
     getClassType,
     getHandle,
     getInstanceType,
     getWrapperClass,
+    peekTypeClass,
+    registerClassStruct,
     registerInterface,
     registerWrapperClass,
+    registerWrapperClassResolver,
     type StaticBase,
     setHandle,
     wrapHandle,
+    type WrapperClassResolver,
 } from "./registry.js";
 /** @public */
-export { connectSignal, disconnectSignal, emitSignal, getSignalBaseName, type SignalHandler } from "./signal.js";
+export {
+    connectSignal,
+    disconnectSignal,
+    emitSignal,
+    getSignalBaseName,
+    type SignalHandler,
+    signalForHandlerName,
+} from "./signal.js";
 /** @public */
 export { t } from "./t.js";
 /** @public */
@@ -79,9 +103,26 @@ export {
     valueIsA,
 } from "./type.js";
 /** @public */
-export { getBoxedValue, setBoxedValue } from "./value.js";
+export {
+    fromValue,
+    getBoxedValue,
+    type JsValue,
+    setBoxedValue,
+    toValueHandle,
+    tryToValueHandle,
+    ValueMarshalError,
+} from "./value.js";
 /** @public */
-export { fromVariant, toVariant, type VariantValue } from "./variant.js";
+export {
+    type ByteArray,
+    type FromVariantOptions,
+    fromVariant,
+    type RecursiveFromVariantOptions,
+    type RecursiveVariantValue,
+    toVariant,
+    type VariantInput,
+    type VariantValue,
+} from "./variant.js";
 /** @public */
 export { callParent, callVfunc } from "./vfunc-call.js";
 /** @public */

package/src/mixin.ts

@@ -89,4 +89,4 @@ function insertMixinLayer(target: AnyClass, mixin: Mixin, inheritedNames: Set<st
     Object.setPrototypeOf(target, layer);
 }
 
-export { insertMixinLayer, installMixins, type MixinReceiver, type Mixin };
+export { copyLayerMembers, insertMixinLayer, installMixins, type MixinReceiver, type Mixin };

package/src/native-value.ts

@@ -1,10 +1,41 @@
-import type { Descriptor, ExternalObject, Handle } from "@gtkx/native";
-import type { ArrayDescriptor, FundamentalDescriptor, HashTableDescriptor, StructDescriptor } from "./descriptors.js";
-import { getHandle, getWrapperClass, wrapCallScopedObject, wrapHandle, wrapObject } from "./registry.js";
+import type { AnyClass } from "@gtkx/utils";
+import {
+    bindFunctionPointer,
+    call,
+    type CallDescriptor,
+    type Descriptor,
+    type ExternalObject,
+    getType,
+    type Handle,
+    type Ref,
+} from "@gtkx/native";
+import {
+    type ArrayDescriptor,
+    boxedT,
+    type CallbackDescriptor,
+    type FundamentalDescriptor,
+    type HashTableDescriptor,
+    isGtypeDescriptor,
+    refT,
+    type StructDescriptor,
+} from "./descriptors.js";
+import { checkError } from "./error.js";
+import { LIB } from "./library.js";
+import {
+    coerceGType,
+    getHandle,
+    getWrapperClass,
+    resolveWrapperClass,
+    wrapCallScopedObject,
+    wrapFundamentalHandle,
+    wrapHandle,
+    wrapObject,
+} from "./registry.js";
 import { resolveDescriptorType } from "./type.js";
 
 type MarshalledKind = "object" | "struct" | "boxed" | "fundamental" | "array" | "hashtable";
 type MarshalledDescriptor = Extract<Descriptor, { kind: MarshalledKind }>;
+type DecodedCallbackTarget = { fnPtr: bigint; userData?: bigint | undefined };
 
 const MARSHALLED_KINDS: Set<Descriptor["kind"]> = new Set<MarshalledKind>([
     "object",
@@ -15,6 +46,8 @@ const MARSHALLED_KINDS: Set<Descriptor["kind"]> = new Set<MarshalledKind>([
     "hashtable",
 ]);
 
+const NULL_POINTER = 0n;
+
 function isMarshalledDescriptor(descriptor: Descriptor): descriptor is MarshalledDescriptor {
     return MARSHALLED_KINDS.has(descriptor.kind);
 }
@@ -32,18 +65,103 @@ function collectionFromNative(descriptor: ArrayDescriptor, value: unknown): unkn
 }
 
 function boxedFromNative(descriptor: Descriptor, value: unknown): unknown {
-    return value == null
-        ? null
-        : wrapHandle(value as ExternalObject<Handle>, getWrapperClass(resolveDescriptorType(descriptor)));
+    if (value == null) {
+        return null;
+    }
+
+    const handle = value as ExternalObject<Handle>;
+    const type = resolveDescriptorType(descriptor);
+
+    return wrapHandle(handle, getWrapperClass(type));
+}
+
+function fundamentalWrapperClass(descriptor: FundamentalDescriptor, handle: ExternalObject<Handle>): AnyClass {
+    if (descriptor.wrapperClass !== undefined) {
+        return descriptor.wrapperClass;
+    }
+
+    const declaredType = resolveDescriptorType(descriptor);
+
+    return resolveWrapperClass(getType(handle, declaredType)) ?? getWrapperClass(declaredType);
 }
 
 function fundamentalFromNative(descriptor: FundamentalDescriptor, value: unknown): unknown {
-    return value == null
-        ? null
-        : wrapHandle(
-                value as ExternalObject<Handle>,
-                descriptor.wrapperClass ?? getWrapperClass(resolveDescriptorType(descriptor)),
-            );
+    if (value == null) {
+        return null;
+    }
+
+    const handle = value as ExternalObject<Handle>;
+
+    return wrapFundamentalHandle(handle, fundamentalWrapperClass(descriptor, handle));
+}
+
+const errorRefDescriptor = (): Descriptor =>
+    refT(boxedT("GError", { ownership: "full", sharedLibrary: LIB, getTypeFnName: "g_error_get_type" }));
+
+function decodedCallbackValues(
+    descriptor: CallbackDescriptor,
+    target: DecodedCallbackTarget,
+    inputs: unknown[],
+): unknown[] {
+    const values: unknown[] = [];
+    let cursor = 0;
+
+    for (const [index, argDescriptor] of descriptor.argDescriptors.entries()) {
+        if (index === descriptor.userDataIndex) {
+            values.push(target.userData ?? NULL_POINTER);
+        } else {
+            values.push(toNative(argDescriptor, inputs[cursor]));
+            cursor += 1;
+        }
+    }
+
+    return values;
+}
+
+function decodedCallbackCallable(
+    descriptor: CallbackDescriptor,
+    target: DecodedCallbackTarget,
+): (...inputs: unknown[]) => unknown {
+    const canThrow = descriptor.canThrow === true;
+    const isOneShot = descriptor.scope === "async";
+    const argDescriptors = canThrow ? [...descriptor.argDescriptors, errorRefDescriptor()] : descriptor.argDescriptors;
+    let bound: ExternalObject<CallDescriptor> | undefined;
+    let isSpent = false;
+
+    return (...inputs) => {
+        if (isSpent) {
+            throw new Error("An async-scoped callback was already invoked; its native caller has released it");
+        }
+
+        bound ??= bindFunctionPointer(target.fnPtr, argDescriptors, descriptor.returnDescriptor, "decoded callback");
+        const values = decodedCallbackValues(descriptor, target, inputs);
+        isSpent = isOneShot;
+
+        if (!canThrow) {
+            return fromNative(descriptor.returnDescriptor, call(bound, values));
+        }
+
+        const errorRef: Ref = { value: null };
+        values.push(errorRef);
+        const result = call(bound, values);
+        checkError(errorRef);
+
+        return fromNative(descriptor.returnDescriptor, result);
+    };
+}
+
+function callbackFromNative(descriptor: CallbackDescriptor, value: unknown): unknown {
+    if (value == null) {
+        return value;
+    }
+
+    const target = value as Partial<DecodedCallbackTarget>;
+
+    if (typeof target.fnPtr !== "bigint") {
+        return value;
+    }
+
+    return decodedCallbackCallable(descriptor, { fnPtr: target.fnPtr, userData: target.userData });
 }
 
 function hashTableFromNative(descriptor: HashTableDescriptor, value: unknown): unknown {
@@ -64,12 +182,21 @@ function hashTableFromNative(descriptor: HashTableDescriptor, value: unknown): u
 /**
  * Converts a raw value returned from native code into its JavaScript form,
  * wrapping object, struct, boxed, and fundamental handles and recursively
- * converting arrays and hash tables according to the descriptor.
+ * converting arrays and hash tables according to the descriptor. A callback
+ * decoded from a native function pointer and its bound user data becomes a
+ * callable function that invokes the native callback; it stays valid only as
+ * long as the native caller keeps the pointer pair alive, which for an
+ * async-scoped callback means until the first invocation — calling one a
+ * second time throws instead of reaching the released native closure.
  *
  * @param descriptor Describes the native type of the value.
  * @param value The raw native value to convert.
  */
 function fromNative(descriptor: Descriptor, value: unknown): unknown {
+    if (descriptor.kind === "callback") {
+        return callbackFromNative(descriptor, value);
+    }
+
     if (!isMarshalledDescriptor(descriptor)) {
         return value;
     }
@@ -113,13 +240,18 @@ function hashTableToNative(descriptor: HashTableDescriptor, value: unknown): unk
 
 /**
  * Converts a JavaScript value into the raw form native code expects, unwrapping
- * object, struct, boxed, and fundamental wrappers back to their handles and
+ * object, struct, boxed, and fundamental wrappers back to their handles,
+ * resolving a class passed for a GType to the GType it was registered under, and
  * recursively converting arrays and maps according to the descriptor.
  *
  * @param descriptor Describes the native type to convert to.
  * @param value The JavaScript value to convert.
  */
 function toNative(descriptor: Descriptor, value: unknown): unknown {
+    if (isGtypeDescriptor(descriptor)) {
+        return coerceGType(value);
+    }
+
     if (!isMarshalledDescriptor(descriptor)) {
         return value;
     }

package/src/object.ts

@@ -3,9 +3,9 @@ import { type AnyClass, getParentClass } from "@gtkx/utils";
 import { bind } from "./bind.js";
 import { objectT, stringT, voidT } from "./descriptors.js";
 import { LIB, VALUE_T } from "./library.js";
-import { type ConstructProperty, constructPropertyFor } from "./properties.js";
+import { coercePropertyValue, type ConstructProperty, constructPropertyFor } from "./properties.js";
 import { getHandle, registerWrapper } from "./registry.js";
-import { fromValue, newValueForDescriptor, toValue } from "./value.js";
+import { fromValueForDescriptor, newValueForDescriptor, toValue } from "./value.js";
 
 /**
  * One construct property a wrapper class accepts: the canonical `GObject` name it is set under,
@@ -110,7 +110,7 @@ function constructPropertyForEntry(
         return constructPropertyFor(source.gtype, name, value, source.wrapper);
     }
 
-    return { name: binding[0], value: toValue(binding[1], value) };
+    return { name: binding[0], value: toValue(binding[1], coercePropertyValue(source.gtype, binding[0], value)) };
 }
 
 /**
@@ -123,17 +123,24 @@ function constructPropertyForEntry(
  * for a read-only property and for a value of a type the property cannot hold, and
  * a `RangeError` for a value the ParamSpec rejects. A value marshalled through a
  * declared descriptor is converted rather than checked, so a `null` handed to a
- * numeric one of those lands 0 rather than being refused.
+ * numeric one of those lands 0 rather than being refused, and a number is fitted to
+ * the property first, as `coerceObjectProperty` does: truncated toward zero for a
+ * whole-number property and clamped to the range its `GObject.ParamSpec` allows.
  * Properties whose value is `undefined` are skipped. A type registered with
  * `registerClass` binds the wrapper before its `constructed` slot runs, so an
  * override of that slot already sees a usable instance.
+ * When construction returns an object that already has a wrapper — it reached
+ * JavaScript and was wrapped before `g_object_new` returned, for example a
+ * `Gtk.Window` observed through the toplevels list — that existing wrapper is
+ * returned instead of binding `wrapper`, so both references stay one object.
  *
  * @param gtype The GType of the object to construct.
  * @param props Property names mapped to the values to set them to.
  * @param wrapper The wrapper instance to bind to the new object.
- * @returns The handle of the newly created object.
+ * @returns The wrapper bound to the constructed object: `wrapper` itself, or
+ * the wrapper the object already had.
  */
-function newObjectWithProperties(gtype: bigint, props: object, wrapper: object): ExternalObject<Handle> {
+function newObjectWithProperties<T extends object>(gtype: bigint, props: object, wrapper: T): T {
     const names: string[] = [];
     const values: ExternalObject<Handle>[] = [];
     const bindings = constructBindingsFor(wrapper.constructor as AnyClass | undefined);
@@ -148,9 +155,13 @@ function newObjectWithProperties(gtype: bigint, props: object, wrapper: object):
         }
     }
 
-    newObject(gtype, names, values, wrapper, registerWrapper);
+    const existing = newObject(gtype, names, values, wrapper, registerWrapper);
 
-    return getHandle(wrapper);
+    if (existing !== null) {
+        return existing as T;
+    }
+
+    return wrapper;
 }
 
 /**
@@ -165,15 +176,16 @@ function getObjectProperty(obj: object, propertyName: string, descriptor: Descri
     const value = newValueForDescriptor(descriptor);
     gObjectGetProperty(getHandle(obj), propertyName, value);
 
-    return fromValue(value);
+    return fromValueForDescriptor(descriptor, value);
 }
 
 /**
  * Writes a JavaScript value to a GObject property, converting it to native form
  * using the descriptor. The descriptor converts what it is given rather than checking it against
  * the property's `GObject.ParamSpec`, so `null` and `undefined` written to a numeric or enum
- * property land 0, where the same write to a property installed through `registerClass` is
- * refused with a `TypeError`.
+ * property land 0, and a fractional number written to a whole-number property is truncated toward
+ * zero, where the same writes to a property installed through `registerClass` are refused with a
+ * `TypeError`.
  *
  * @param obj The object to write to.
  * @param propertyName The property name.