@gtkx/runtime 1.0.0 → 1.2.0

package/src/registry.ts

@@ -11,11 +11,14 @@ import type { Mixin, MixinReceiver } from "./mixin.js";
 import { TYPE_INVALID, type TypedClass, typeInterfaces, typeIsA, typeName, typeParent } from "./type.js";
 
 /**
- * Static side of class `C` with its construct signature preserved but the member
- * named `K` (default `"new"`) removed.
+ * Static side of class `C` with its construct signature preserved but the members named `K`
+ * removed. A generated class lists every static it declares itself, so a static it narrows never
+ * has to stay assignable to the one it shadows. The signature is kept abstract so an abstract `C`
+ * survives it: a subclass extends the result, and only the subclass's own declarations decide
+ * which statics reach it.
  */
-type StaticBase<C, K extends PropertyKey = "new"> = Omit<C, K> &
-    (C extends new (...args: infer A) => infer R ? new (...args: A) => R : never);
+type StaticBase<C, K extends PropertyKey> = Omit<C, K> &
+    (C extends abstract new (...args: infer A) => infer R ? abstract new (...args: A) => R : never);
 
 /** One overridable vtable slot: where it sits in the vtable struct and how it is marshalled. */
 type VfuncDescriptor = {
@@ -35,6 +38,12 @@ type VfuncDescriptor = {
     argDescriptors: NativeRegisterClassVfunc["argDescriptors"];
     /** Descriptor for the value the slot returns. */
     returnDescriptor: NativeRegisterClassVfunc["returnDescriptor"];
+    /**
+     * GIR marks the slot's return value as one the bindings do not surface, so a call through the
+     * slot drops it and an implementation of the slot reports success in its place, while
+     * `VfuncDescriptor.returnDescriptor` keeps the C type the slot is called against either way.
+     */
+    isReturnSkipped?: boolean;
     /**
      * The slot takes a trailing `GError**` that `VfuncDescriptor.argDescriptors` leaves out, the
      * way GIR leaves it out of a callable's parameters. A call through the slot has to append it
@@ -48,6 +57,7 @@ type VfuncDescriptor = {
  * overrides each one.
  */
 type VfuncRegistry = Record<string, VfuncDescriptor>;
+type WrapperBinding = (handle: ExternalObject<Handle>, instance: object) => void;
 
 /**
  * How one property an interface declares reaches the vtable, given as the interface's own accessor
@@ -320,24 +330,18 @@ function resolveComposedClass(runtimeType: bigint): AnyClass | null {
 }
 
 function wrapObject(value: unknown): object | null {
-    if (value == null) {
-        return null;
-    }
-
-    return getOrCreateWrapper(value as ExternalObject<Handle>);
+    return value == null ? null : getOrCreateWrapper(value as ExternalObject<Handle>);
 }
 
-function getOrCreateWrapper(handle: ExternalObject<Handle>): object {
-    if (handleMap.has(handle)) {
-        return handle;
-    }
-
-    const existing = getWrapper(handle);
+function wrapCallScopedObject(value: unknown): object | null {
+    return value == null ? null : wrapperFor(value as ExternalObject<Handle>, bindCallScopedWrapper);
+}
 
-    if (existing) {
-        return existing;
-    }
+function existingWrapperFor(handle: ExternalObject<Handle>): object | null {
+    return handleMap.has(handle) ? handle : getWrapper(handle);
+}
 
+function createWrapper(handle: ExternalObject<Handle>): object {
     const runtimeType: bigint = getType(handle);
 
     if (runtimeType === TYPE_INVALID) {
@@ -350,12 +354,26 @@ function getOrCreateWrapper(handle: ExternalObject<Handle>): object {
         throw new Error(`Expected registered GLib type, got type ${String(runtimeType)}`);
     }
 
-    const instance: object = Object.create(cls.prototype) as object;
-    registerWrapper(handle, instance);
+    return Object.create(cls.prototype) as object;
+}
+
+function wrapperFor(handle: ExternalObject<Handle>, bind: WrapperBinding): object {
+    const existing = existingWrapperFor(handle);
+
+    if (existing) {
+        return existing;
+    }
+
+    const instance = createWrapper(handle);
+    bind(handle, instance);
 
     return instance;
 }
 
+function getOrCreateWrapper(handle: ExternalObject<Handle>): object {
+    return wrapperFor(handle, registerWrapper);
+}
+
 function instanceClassName(instance: object): string {
     return (instance as { constructor?: { name?: string } }).constructor?.name ?? "object";
 }
@@ -376,6 +394,10 @@ function setHandle(instance: object, handle: ExternalObject<Handle>): void {
     handleMap.set(instance, handle);
 }
 
+function bindCallScopedWrapper(handle: ExternalObject<Handle>, instance: object): void {
+    setHandle(instance, handle);
+}
+
 function registerWrapper(handle: ExternalObject<Handle>, instance: object): void {
     setHandle(instance, handle);
     setWrapper(handle, instance);
@@ -416,6 +438,7 @@ export {
     instanceClassName,
     registerWrapper,
     resolveWrapperType,
+    wrapCallScopedObject,
     wrapObject,
     type InterfaceProperty,
     type StaticBase,

package/src/signal.ts

@@ -43,6 +43,11 @@ type SignalConnectSpec = {
     isAfter: boolean;
 };
 
+type EmitValues = {
+    values: ExternalObject<Handle>[];
+    reads: (() => unknown)[];
+};
+
 /** One argument of a signal emission: how to marshal it, plus the value to marshal. */
 type EmitArg = Arg & {
     /**
@@ -194,7 +199,7 @@ function connectBind(type: bigint, signal: string, callback: CallbackDescriptor)
  */
 function connectSignal(instance: object, signal: string, spec: SignalConnectSpec): number {
     const { callback, handler, isAfter } = spec;
-    const wrapped = wrapCallback(handler, callback, "emitter");
+    const wrapped = wrapCallback(handler, callback, "signal");
     const type: bigint = (instance as TypedClass).__type__;
     const connect = connectBind(type, signal, callback);
     const handlerId = connect(getHandle(instance), signal, wrapped, isAfter ? 1 : 0) as number;
@@ -221,47 +226,46 @@ const createEmitValue = (arg: EmitArg): { value: ExternalObject<Handle>; read?:
     return isInoutArg(arg) ? outValueForDescriptor(arg.type, arg.value) : outValueForDescriptor(arg.type);
 };
 
+const collectEmitValues = (instance: object, args: EmitArg[]): EmitValues => {
+    const collected: EmitValues = { values: [toValue(objectT("full"), instance)], reads: [] };
+
+    for (const arg of args) {
+        const { value, read } = createEmitValue(arg);
+        collected.values.push(value);
+
+        if (read) {
+            collected.reads.push(read);
+        }
+    }
+
+    return collected;
+};
+
+const readEmitOutputs = (reads: (() => unknown)[]): unknown[] => reads.map((read) => read());
+
 /**
  * Emits a signal on an instance with the given arguments and returns its result
  * combined with any output-argument values.
  * @param instance Emitter to emit the signal on.
  * @param signal Signal name, optionally including a `::detail` suffix.
  * @param args Arguments to pass, including output and inout arguments.
- * @param returnDescriptor Descriptor for the signal's return value, omitted when it returns void.
+ * @param returns Descriptor for the signal's return value, omitted when it returns void.
  */
-function emitSignal(instance: object, signal: string, args: EmitArg[], returnDescriptor?: Descriptor): unknown {
+function emitSignal(instance: object, signal: string, args: EmitArg[], returns?: Descriptor): unknown {
     const signalId = getSignalId(instance, signal);
     const detail = getSignalDetailQuark(signal);
-    const values: ExternalObject<Handle>[] = [toValue(objectT("full"), instance)];
-    const reads: (() => unknown)[] = [];
-
-    for (const arg of args) {
-        const { value, read } = createEmitValue(arg);
-        values.push(value);
+    const { values, reads } = collectEmitValues(instance, args);
 
-        if (read) {
-            reads.push(read);
-        }
-    }
+    if (returns === undefined) {
+        gSignalEmitv(values, signalId, detail, undefined);
 
-    if (returnDescriptor !== undefined) {
-        const returnValue = newValueForDescriptor(returnDescriptor);
-        gSignalEmitv(values, signalId, detail, returnValue);
-
-        return packTupleResult(
-            reads.map((read) => read()),
-            fromValue(returnValue),
-            true,
-        );
+        return packTupleResult(readEmitOutputs(reads), undefined, false);
     }
 
-    gSignalEmitv(values, signalId, detail, undefined);
+    const returnValue = newValueForDescriptor(returns);
+    gSignalEmitv(values, signalId, detail, returnValue);
 
-    return packTupleResult(
-        reads.map((read) => read()),
-        undefined,
-        false,
-    );
+    return packTupleResult(readEmitOutputs(reads), fromValue(returnValue), true);
 }
 
 export {

package/src/t.ts

@@ -69,7 +69,7 @@ type T = {
     slist: typeof helpers.slistT;
     /** Builds a descriptor for a `GPtrArray` of items. */
     ptrArray: typeof helpers.ptrArrayT;
-    /** Builds a descriptor for a `GArray` of items, optionally with an explicit element size. */
+    /** Builds a descriptor for a `GArray` of items. */
     gArray: typeof helpers.gArrayT;
     /** Builds a descriptor for a `GByteArray`. */
     byteArray: typeof helpers.byteArrayT;
@@ -77,6 +77,8 @@ type T = {
     sizedArray: typeof helpers.sizedArrayT;
     /** Builds a descriptor for a C array of a fixed length. */
     fixedArray: typeof helpers.fixedArrayT;
+    /** Builds a descriptor for an out pointer into the buffer another argument supplied. */
+    cursorArray: typeof helpers.cursorArrayT;
     /** Builds a descriptor for a function pointer, marshalling a JavaScript function into a native closure. */
     callback: typeof helpers.callbackT;
     /**
@@ -127,6 +129,7 @@ const t: T = {
     byteArray: helpers.byteArrayT,
     sizedArray: helpers.sizedArrayT,
     fixedArray: helpers.fixedArrayT,
+    cursorArray: helpers.cursorArrayT,
     callback: helpers.callbackT,
     fn,
 };

package/src/tuple.ts

@@ -1,3 +1,10 @@
+import type { Descriptor } from "@gtkx/native";
+
+type SplitResult = { primary: unknown; outValues: unknown[] };
+
+const hasSurfacedPrimary = (returnDescriptor: Descriptor, isReturnSkipped: boolean | undefined): boolean =>
+    returnDescriptor.kind !== "void" && isReturnSkipped !== true;
+
 const packTupleResult = (outs: unknown[], primary: unknown, hasPrimary: boolean): unknown => {
     if (hasPrimary) {
         return outs.length === 0 ? primary : [primary, ...outs];
@@ -14,19 +21,15 @@ const packTupleResult = (outs: unknown[], primary: unknown, hasPrimary: boolean)
     return outs;
 };
 
-const splitTupleResult = (
-    result: unknown,
-    hasPrimary: boolean,
-    outCount: number,
-): { primary: unknown; outValues: unknown[] } => {
-    if (hasPrimary) {
-        if (Array.isArray(result)) {
-            return { primary: result[0], outValues: result.slice(1) };
-        }
-
-        return { primary: result, outValues: [] };
+const splitPrimaryResult = (result: unknown, outCount: number): SplitResult => {
+    if (outCount > 0 && Array.isArray(result)) {
+        return { primary: result[0], outValues: result.slice(1) };
     }
 
+    return { primary: result, outValues: [] };
+};
+
+const splitOutResult = (result: unknown, outCount: number): SplitResult => {
     if (outCount === 1) {
         return { primary: undefined, outValues: [result] };
     }
@@ -34,4 +37,7 @@ const splitTupleResult = (
     return { primary: undefined, outValues: Array.isArray(result) ? result : [] };
 };
 
-export { packTupleResult, splitTupleResult };
+const splitTupleResult = (result: unknown, hasPrimary: boolean, outCount: number): SplitResult =>
+    hasPrimary ? splitPrimaryResult(result, outCount) : splitOutResult(result, outCount);
+
+export { hasSurfacedPrimary, packTupleResult, splitTupleResult };

package/src/value.ts

@@ -9,6 +9,9 @@ import {
     boxedT,
     float32T,
     float64T,
+    type FundamentalDescriptor,
+    fundamentalLifecycleFor,
+    fundamentalT,
     int8T,
     int32T,
     objectT,
@@ -61,10 +64,13 @@ type ValueType = {
 
 type ValueGetter = (value: ExternalObject<Handle>) => unknown;
 type ValueWriter = ValueType["set"];
+type ValueNarrower = (jsValue: unknown) => unknown;
 
 const setBoxedCache = createBindCache();
 const setStaticBoxedCache = createBindCache();
 const dupBoxedCache = createBindCache();
+const setInstanceCache = createBindCache();
+const peekPointerCache = createBindCache();
 const gValueInit = bind(LIB, "g_value_init", [VALUE_T, biguint64T], voidT);
 const gValueCopy = bind(LIB, "g_value_copy", [VALUE_T, VALUE_T], voidT);
 const booleanValueType = bindValueType("boolean", booleanT);
@@ -86,9 +92,10 @@ const objectValueType = bindValueType("object", objectT("borrowed"));
 const paramValueType = bindValueType("param", PARAM_T);
 const variantValueType = bindValueType("variant", VARIANT_T);
 const pointerValueType = bindValueType("pointer", uint64T);
+const setStrvBoxed = bind(LIB, "g_value_set_boxed", [VALUE_T, arrayT(stringT("borrowed"))], voidT);
 
 const strvValueType: ValueType = {
-    set: bind(LIB, "g_value_set_boxed", [VALUE_T, arrayT(stringT("borrowed"))], voidT),
+    set: setStrvValue,
     get: bind(LIB, "g_value_get_boxed", [VALUE_T], arrayT(stringT("borrowed"))),
 };
 
@@ -112,7 +119,6 @@ const PLAIN_VALUE_TYPES: Partial<Record<Descriptor["kind"], ValueType>> = {
 
 const PLAIN_VALUE_GETTERS: Map<bigint, ValueGetter> = new Map([
     [TYPE_BOOLEAN, booleanValueType.get],
-    [TYPE_GTYPE, typeValueType.get],
     [TYPE_CHAR, scharValueType.get],
     [TYPE_UCHAR, ucharValueType.get],
     [TYPE_INT, intValueType.get],
@@ -129,7 +135,6 @@ const PLAIN_VALUE_GETTERS: Map<bigint, ValueGetter> = new Map([
 
 const PLAIN_VALUE_SETTERS: Map<bigint, ValueType["set"]> = new Map([
     [TYPE_BOOLEAN, booleanValueType.set],
-    [TYPE_GTYPE, typeValueType.set],
     [TYPE_CHAR, scharValueType.set],
     [TYPE_UCHAR, ucharValueType.set],
     [TYPE_INT, intValueType.set],
@@ -182,6 +187,46 @@ const boxedValueType = (type: bigint): ValueType => {
 const enumOrFlagsValueType = (type: bigint): ValueType =>
     typeFundamental(type) === TYPE_FLAGS ? flagsValueType : enumValueType;
 
+function unsupportedFundamental(type: bigint): never {
+    throw new Error(`Unsupported fundamental type '${typeName(type) ?? String(type)}' for value`);
+}
+
+const setInstanceBind = (fundamental: bigint, descriptor: FundamentalDescriptor) =>
+    setInstanceCache(String(fundamental), LIB, "g_value_set_instance", [VALUE_T, descriptor], voidT);
+
+const peekPointerBind = (fundamental: bigint, descriptor: FundamentalDescriptor) =>
+    peekPointerCache(String(fundamental), LIB, "g_value_peek_pointer", [VALUE_T], descriptor);
+
+const customFundamentalDescriptor = (fundamental: bigint): FundamentalDescriptor | undefined => {
+    const name = typeName(fundamental);
+
+    if (name === null) {
+        return undefined;
+    }
+
+    const lifecycle = fundamentalLifecycleFor(name);
+
+    if (lifecycle === undefined) {
+        return undefined;
+    }
+
+    return fundamentalT(lifecycle.sharedLibrary, lifecycle.refFnName, lifecycle.unrefFnName, {
+        ownership: "borrowed",
+        typeName: name,
+    });
+};
+
+const customFundamentalValueType = (type: bigint): ValueType | undefined => {
+    const fundamental = typeFundamental(type);
+    const descriptor = customFundamentalDescriptor(fundamental);
+
+    if (descriptor === undefined) {
+        return undefined;
+    }
+
+    return { set: setInstanceBind(fundamental, descriptor), get: peekPointerBind(fundamental, descriptor) };
+};
+
 const fundamentalValueType = (type: bigint): ValueType => {
     switch (typeFundamental(type)) {
         case TYPE_PARAM: {
@@ -194,7 +239,7 @@ const fundamentalValueType = (type: bigint): ValueType => {
             return boxedValueType(type);
         }
         default: {
-            throw new Error(`Unsupported fundamental type '${typeName(type) ?? String(type)}' for value`);
+            return customFundamentalValueType(type) ?? unsupportedFundamental(type);
         }
     }
 };
@@ -332,6 +377,10 @@ function setStringValue(value: ExternalObject<Handle>, nativeValue: unknown): vo
     stringValueType.set(value, nativeValue ?? null);
 }
 
+function setStrvValue(value: ExternalObject<Handle>, nativeValue: unknown): void {
+    setStrvBoxed(value, nativeValue ?? null);
+}
+
 function setPointerValue(value: ExternalObject<Handle>, nativeValue: unknown): void {
     if (nativeValue != null) {
         throw new Error("G_TYPE_POINTER non-null values cannot be marshalled from JS");
@@ -350,22 +399,51 @@ function setBoxedFromValue(value: ExternalObject<Handle>, nativeValue: unknown):
     setBoxedValue(value, nativeValue ?? null);
 }
 
-const resolveValueGetter = (fundamental: bigint): ValueGetter | undefined =>
+const customFundamentalGetter = (type: bigint): ValueGetter | undefined => {
+    const valueType = customFundamentalValueType(type);
+
+    if (valueType === undefined) {
+        return undefined;
+    }
+
+    return (value) => wrapHandle(valueType.get(value) as ExternalObject<Handle> | null, getWrapperClass(type));
+};
+
+const customFundamentalSetter = (type: bigint): ValueType["set"] | undefined => {
+    const valueType = customFundamentalValueType(type);
+
+    return valueType === undefined ? undefined : handleSetter(valueType);
+};
+
+const builtInValueGetter = (fundamental: bigint): ValueGetter | undefined =>
     PLAIN_VALUE_GETTERS.get(fundamental) ?? wrappedValueGetter(fundamental);
 
-const resolveValueSetter = (fundamental: bigint): ValueType["set"] | undefined =>
+const builtInValueSetter = (fundamental: bigint): ValueType["set"] | undefined =>
     PLAIN_VALUE_SETTERS.get(fundamental) ?? WRAPPED_VALUE_SETTERS.get(fundamental);
 
-function setStrvValue(value: ExternalObject<Handle>, jsValue: unknown): void {
-    strvValueType.set(value, jsValue ?? null);
+const exactValueType = (type: bigint): ValueType | undefined => {
+    if (type === TYPE_GTYPE) {
+        return typeValueType;
+    }
+
+    return type === getStrvType() ? strvValueType : undefined;
+};
+
+const resolveValueGetter = (type: bigint): ValueGetter | undefined =>
+    exactValueType(type)?.get ?? builtInValueGetter(typeFundamental(type)) ?? customFundamentalGetter(type);
+
+const resolveValueSetter = (type: bigint): ValueType["set"] | undefined =>
+    exactValueType(type)?.set ?? builtInValueSetter(typeFundamental(type)) ?? customFundamentalSetter(type);
+
+const holdsUnchanged: ValueNarrower = (jsValue) => jsValue;
+const holdsAsFloat: ValueNarrower = (jsValue) => Math.fround(jsValue as number);
+
+function valueNarrowerFor(type: bigint): ValueNarrower {
+    return typeFundamental(type) === TYPE_FLOAT ? holdsAsFloat : holdsUnchanged;
 }
 
 function valueWriterFor(type: bigint): ValueWriter {
-    if (type === getStrvType()) {
-        return setStrvValue;
-    }
-
-    const set = resolveValueSetter(typeFundamental(type));
+    const set = resolveValueSetter(type);
 
     if (set === undefined) {
         throw new Error(`Unsupported type for intoValue: ${typeName(type) ?? String(type)}`);
@@ -407,12 +485,7 @@ function toValue(descriptor: Descriptor, value: unknown): ExternalObject<Handle>
 
 function fromValue(value: ExternalObject<Handle>): unknown {
     const type = getValueType(value);
-
-    if (type === getStrvType()) {
-        return strvValueType.get(value);
-    }
-
-    const get = resolveValueGetter(typeFundamental(type));
+    const get = resolveValueGetter(type);
 
     if (get === undefined) {
         throw new Error(`Unsupported type for fromValue: ${typeName(type) ?? String(type)}`);
@@ -463,6 +536,8 @@ export {
     outValueForDescriptor,
     outValueForBoxedDescriptor,
     inoutValueForBoxedDescriptor,
+    type ValueNarrower,
+    valueNarrowerFor,
     type ValueWriter,
     valueWriterFor,
 };

package/src/vfunc-call.ts

@@ -82,7 +82,11 @@ function buildInvoker(slot: ResolvedSlot, instanceType: bigint | undefined, call
 
     const shaped = fromNativeCallable(
         bindVfunc(bindOptionsFor(slot, instanceType, args, label)),
-        { args, returns: descriptor.returnDescriptor, canThrow },
+        {
+            args,
+            returns: descriptor.returnDescriptor,
+            canThrow,
+        },
         takeRefSeeds,
     );
 

package/src/vfunc.ts

@@ -2,6 +2,7 @@ import type { Descriptor } from "@gtkx/native";
 import { type AnyClass, getParentClass, walkClassChain } from "@gtkx/utils";
 import type { Arg } from "./arg.js";
 import { isCallerAllocatedOut } from "./callback.js";
+import { foldedLengthSources } from "./folded-lengths.js";
 import { getInterfaceVfuncRegistry, getVfuncRegistry, type VfuncDescriptor } from "./registry.js";
 
 function findClassVfuncDescriptor(klass: AnyClass, methodName: string): VfuncDescriptor | null {
@@ -12,9 +13,13 @@ function findInterfaceVfuncDescriptor(interfaceGtype: bigint, methodName: string
     return getInterfaceVfuncRegistry(interfaceGtype)?.[methodName];
 }
 
-function vfuncArg(descriptor: Descriptor): Arg {
+function vfuncArg(descriptor: Descriptor, isFoldedLength: boolean): Arg {
     if (descriptor.kind === "ref") {
-        return { type: descriptor.innerDescriptor, direction: descriptor.inout === true ? "inout" : "out" };
+        return {
+            type: descriptor.innerDescriptor,
+            direction: descriptor.inout === true ? "inout" : "out",
+            isConsumed: isFoldedLength,
+        };
     }
 
     if (isCallerAllocatedOut(descriptor)) {
@@ -25,7 +30,9 @@ function vfuncArg(descriptor: Descriptor): Arg {
 }
 
 function vfuncArgs(descriptor: VfuncDescriptor): Arg[] {
-    return descriptor.argDescriptors.map((argDescriptor) => vfuncArg(argDescriptor));
+    const lengths = foldedLengthSources(descriptor);
+
+    return descriptor.argDescriptors.map((argDescriptor, index) => vfuncArg(argDescriptor, lengths.has(index)));
 }
 
 export { findClassVfuncDescriptor, findInterfaceVfuncDescriptor, vfuncArgs };