@gtkx/runtime 1.0.0-rc.4 → 1.1.0

package/src/registry.ts

@@ -1,4 +1,3 @@
-import type { AnyClass } from "@gtkx/utils";
 import {
     type ExternalObject,
     getType,
@@ -7,60 +6,124 @@ import {
     type RegisterClassVfunc as NativeRegisterClassVfunc,
     setWrapper,
 } from "@gtkx/native";
+import { type AnyClass, walkClassChain } from "@gtkx/utils";
 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.
+ * named `K` (default `"new"`) removed. The signature is kept abstract so an abstract
+ * `C` survives it: a subclass extends the result, and only the subclass's own
+ * declaration decides whether `new` reaches it.
  */
 type StaticBase<C, K extends PropertyKey = "new"> = Omit<C, K> &
-    (C extends new (...args: infer A) => infer R ? new (...args: A) => R : never);
+    (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<K extends "class" | "interface"> = {
-    /** Whether the slot lives in a class struct or in an interface vtable. */
-    kind: K;
+type VfuncDescriptor = {
     /** GIR name of the type struct holding the slot, without its namespace, such as `WidgetClass`. */
     className: string;
     /** Name of the slot's field in that struct. */
     vfuncName: string;
     /** Byte offset of the slot within the struct. */
     byteOffset: number;
-    /** Byte size of the struct, used to bounds-check `VfuncDescriptor.byteOffset`. */
-    vtableSize: number;
+    /**
+     * Byte size of an interface's vtable struct, used to bounds-check `VfuncDescriptor.byteOffset`.
+     * A class struct is bounds-checked against the size `g_type_query` reports for it, so a slot in
+     * one carries no size of its own.
+     */
+    vtableSize?: number;
     /** Descriptor for each argument the slot receives, starting with the instance. */
     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
+     * or it passes one argument fewer than the implementation reads.
+     */
+    canThrow?: boolean;
 };
 
 /**
  * The vtable slots a wrapper class or interface exposes, keyed by the JavaScript method name that
  * overrides each one.
  */
-type VfuncRegistry = Record<string, VfuncDescriptor<"class"> | VfuncDescriptor<"interface">>;
+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
+ * members. A direction introspection does not route through a vtable slot is left out, and the
+ * property owns that direction's state itself.
+ */
+type InterfaceProperty = {
+    /** Member reading the slot the property's value comes from, such as `getEnabled`. */
+    getter?: string;
+    /** Member writing the slot the property's value goes to, such as `setActionName`. */
+    setter?: string;
+};
+
+/**
+ * What an interface's vtable struct looks like, for the classes that adopt the interface.
+ * `g_type_query` reports no size for an interface, so each slot's generated metadata carries the
+ * struct's byte size to bounds-check the slot's offset; an interface introspection describes no
+ * vtable for simply contributes no slots.
+ */
+type InterfaceLayout = {
+    /** The slots the struct declares, keyed by the JavaScript method name that fills each one. */
+    vfuncs?: VfuncRegistry;
+    /**
+     * The properties a vtable slot backs, keyed by canonical property name, so a class adopting the
+     * interface answers `g_object_get` and `g_object_set` with what the slot holds.
+     */
+    properties?: Record<string, InterfaceProperty>;
+};
 
 const classRegistry: Map<bigint, AnyClass> = new Map();
 const interfaceMixinRegistry: Map<bigint, Mixin> = new Map();
 const composedClassRegistry: Map<bigint, AnyClass> = new Map();
 const handleMap: WeakMap<object, ExternalObject<Handle>> = new WeakMap();
 const vfuncRegistry: WeakMap<object, VfuncRegistry> = new WeakMap();
-const interfaceVfuncRegistry: Map<bigint, VfuncRegistry> = new Map();
+const interfaceLayoutRegistry: Map<bigint, InterfaceLayout> = new Map();
+const wrapperClasses: WeakSet<AnyClass> = new WeakSet();
+const derivedClasses: WeakSet<AnyClass> = new WeakSet();
 
 function setClassType(cls: AnyClass, type: bigint): void {
     (cls.prototype as { [K in keyof TypedClass]: TypedClass[K] }).__type__ = type;
 }
 
-function getClassType(cls: AnyClass): bigint {
-    const proto: object = cls.prototype;
+/**
+ * Returns the GType a class was registered under, or the invalid type when it carries none. The tag is
+ * read off the class's own prototype, so a subclass that never went through `registerClass` reports the
+ * invalid type rather than inheriting the one its parent was registered with.
+ */
+function getClassType(cls: AnyClass | undefined): bigint {
+    const proto: object | undefined = cls?.prototype;
+
+    if (proto === undefined || !Object.hasOwn(proto, "__type__")) {
+        return TYPE_INVALID;
+    }
 
-    return Object.hasOwn(proto, "__type__") ? (proto as TypedClass).__type__ : TYPE_INVALID;
+    return (proto as TypedClass).__type__;
 }
 
-/** Returns the GType tag of the given wrapper instance. */
+/**
+ * Returns the GType the given instance's handle carries, or the invalid type when it has no handle.
+ * This is the object's own type rather than the type of the class it was wrapped as, and the two differ
+ * for an object GTK created itself, such as the row widget inside a `Gtk.ListView`, which GTKX wraps as
+ * the nearest registered ancestor.
+ */
 function getInstanceType(instance: object): bigint {
-    return getClassType(instance.constructor as AnyClass);
+    const handle = handleMap.get(instance);
+
+    return handle === undefined ? TYPE_INVALID : getType(handle);
 }
 
 function registerClassType(cls: AnyClass, type: bigint): void {
@@ -83,21 +146,47 @@ function registerClassType(cls: AnyClass, type: bigint): void {
 function registerWrapperClass(cls: AnyClass, type: bigint, vfuncs?: VfuncRegistry): void {
     registerClassType(cls, type);
 
+    if (type !== TYPE_INVALID) {
+        wrapperClasses.add(cls);
+    }
+
     if (vfuncs) {
         registerVfuncRegistry(cls, vfuncs);
     }
 }
 
+function markDerivedClass(cls: AnyClass): void {
+    derivedClasses.add(cls);
+}
+
+function resolveAncestorType(ancestor: AnyClass): bigint | undefined {
+    if (derivedClasses.has(ancestor) || !wrapperClasses.has(ancestor)) {
+        return undefined;
+    }
+
+    return getClassType(ancestor);
+}
+
+function resolveWrapperType(instance: object): bigint {
+    const cls = instance.constructor as AnyClass | undefined;
+
+    if (cls === undefined) {
+        return TYPE_INVALID;
+    }
+
+    return walkClassChain(cls, (ancestor) => resolveAncestorType(ancestor)) ?? TYPE_INVALID;
+}
+
 /**
  * Registers a GInterface, associating its GType with a mixin used to compose the
- * interface onto wrapper classes and an optional virtual function registry.
+ * interface onto wrapper classes and, when introspection describes its vtable, that layout.
  * @param cls Class carrying the interface's GType tag.
  * @param type GType of the interface.
  * @param mixin Mixin that applies the interface to a wrapper class.
- * @param vfuncs Vtable slots the interface exposes, so `registerClass` can bind the ones an
- * implementing class overrides.
+ * @param layout The interface's vtable struct, so `registerClass` can bind the slots an
+ * implementing class overrides and take over the ones it leaves alone.
  */
-function registerInterface(cls: AnyClass, type: bigint, mixin: Mixin, vfuncs?: VfuncRegistry): void {
+function registerInterface(cls: AnyClass, type: bigint, mixin: Mixin, layout?: InterfaceLayout): void {
     if (type === TYPE_INVALID) {
         return;
     }
@@ -105,16 +194,17 @@ function registerInterface(cls: AnyClass, type: bigint, mixin: Mixin, vfuncs?: V
     setClassType(cls, type);
     interfaceMixinRegistry.set(type, mixin);
 
-    if (vfuncs) {
-        registerInterfaceVfuncRegistry(type, vfuncs);
+    if (layout) {
+        interfaceLayoutRegistry.set(type, layout);
     }
 }
 
 /**
  * Wraps a native handle in a JS wrapper instance. With no class, resolves and
- * reuses the wrapper for the handle's runtime GType (composing interface mixins);
- * with an explicit class, creates a bare instance backed by the handle. Returns
- * null for a null or undefined handle.
+ * reuses the wrapper for the handle's runtime GType (composing interface mixins),
+ * and hands back an instance that already carries a handle unchanged; with an
+ * explicit class, creates a bare instance backed by the handle. Returns null for
+ * a null or undefined handle.
  * @param handle Native handle to wrap.
  * @param cls Wrapper class to instantiate, or omitted to resolve it from the runtime type.
  */
@@ -174,12 +264,16 @@ function resolveWrapperClass(type: bigint): AnyClass | null {
     return null;
 }
 
+function getInterfaceMixin(type: bigint): Mixin | undefined {
+    return interfaceMixinRegistry.get(type);
+}
+
 function applyInterfaceMixin(cls: AnyClass, type: bigint, baseType: bigint, applied: Set<bigint>): AnyClass {
     if (applied.has(type) || typeIsA(baseType, type)) {
         return cls;
     }
 
-    const mixin = interfaceMixinRegistry.get(type);
+    const mixin = getInterfaceMixin(type);
 
     if (mixin === undefined) {
         return cls;
@@ -228,18 +322,25 @@ function resolveComposedClass(runtimeType: bigint): AnyClass | null {
     }
 
     setClassType(composed, runtimeType);
+    wrapperClasses.add(composed);
     composedClassRegistry.set(runtimeType, composed);
 
     return composed;
 }
 
-function getOrCreateWrapper(handle: ExternalObject<Handle>): object {
-    const existing = getWrapper(handle);
+function wrapObject(value: unknown): object | null {
+    return value == null ? null : getOrCreateWrapper(value as ExternalObject<Handle>);
+}
 
-    if (existing) {
-        return existing;
-    }
+function wrapCallScopedObject(value: unknown): object | null {
+    return value == null ? null : wrapperFor(value as ExternalObject<Handle>, bindCallScopedWrapper);
+}
+
+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) {
@@ -252,34 +353,50 @@ 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";
+}
+
 /** Returns the native handle bound to a wrapper instance, throwing if none is set. */
 function getHandle(instance: object): ExternalObject<Handle> {
     const handle = handleMap.get(instance);
 
     if (handle === undefined) {
-        const name = (instance as { constructor?: { name?: string } }).constructor?.name ?? "object";
-        throw new Error(`No native handle associated with ${name}`);
+        throw new Error(`No native handle associated with ${instanceClassName(instance)}`);
     }
 
     return handle;
 }
 
-/** Returns the native handle bound to an instance, or undefined when there is none or the instance is null. */
-function tryGetHandle(instance: object | null | undefined): ExternalObject<Handle> | undefined {
-    return instance == null ? undefined : handleMap.get(instance);
-}
-
 /** Associates a native handle with a wrapper instance. */
 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);
@@ -293,21 +410,18 @@ function getVfuncRegistry(cls: object): VfuncRegistry | undefined {
     return vfuncRegistry.get(cls);
 }
 
-function registerInterfaceVfuncRegistry(type: bigint, registry: VfuncRegistry): void {
-    if (type === TYPE_INVALID) {
-        return;
-    }
-
-    interfaceVfuncRegistry.set(type, registry);
+function getInterfaceVfuncRegistry(type: bigint): VfuncRegistry | undefined {
+    return interfaceLayoutRegistry.get(type)?.vfuncs;
 }
 
-function getInterfaceVfuncRegistry(type: bigint): VfuncRegistry | undefined {
-    return interfaceVfuncRegistry.get(type);
+function getInterfaceProperties(type: bigint): Record<string, InterfaceProperty> | undefined {
+    return interfaceLayoutRegistry.get(type)?.properties;
 }
 
 export {
     getClassType,
     getInstanceType,
+    markDerivedClass,
     registerClassType,
     registerWrapperClass,
     registerInterface,
@@ -315,11 +429,17 @@ export {
     getWrapperClass,
     resolveWrapperClass,
     getHandle,
-    tryGetHandle,
     setHandle,
     getVfuncRegistry,
+    getInterfaceMixin,
+    getInterfaceProperties,
     getInterfaceVfuncRegistry,
+    instanceClassName,
+    registerWrapper,
+    resolveWrapperType,
+    wrapCallScopedObject,
+    wrapObject,
+    type InterfaceProperty,
     type StaticBase,
     type VfuncDescriptor,
-    type VfuncRegistry,
 };

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 & {
     /**
@@ -53,6 +58,7 @@ type EmitArg = Arg & {
 };
 
 const connectCache = createBindCache();
+const connectionTable: WeakMap<object, Map<string, Set<number>>> = new WeakMap();
 const gQuarkFromString = bind(LIB, "g_quark_from_string", [stringT("borrowed")], uint32T);
 const gSignalLookup = bind(LIB, "g_signal_lookup", [stringT("borrowed"), biguint64T], uint32T);
 
@@ -63,13 +69,6 @@ const gSignalEmitv = bind(
     voidT,
 );
 
-const gSignalHandlersBlockMatched = bind(
-    LIB,
-    "g_signal_handlers_block_matched",
-    [objectT("borrowed"), uint32T, uint32T, uint32T, objectT("borrowed"), objectT("borrowed"), objectT("borrowed")],
-    uint32T,
-);
-
 const gSignalHandlerIsConnected = bind(
     LIB,
     "g_signal_handler_is_connected",
@@ -77,6 +76,8 @@ const gSignalHandlerIsConnected = bind(
     booleanT,
 );
 
+const gSignalHandlerDisconnect = bind(LIB, "g_signal_handler_disconnect", [objectT("borrowed"), uint64T], voidT);
+
 /** Returns the signal name without its detail suffix (the part after `::`). */
 const getSignalBaseName = (signal: string): string => {
     const detailIndex = signal.indexOf("::");
@@ -97,6 +98,81 @@ function getSignalDetailQuark(signal: string): number {
 const isSignalHandlerConnected = (instance: object, handlerId: number): boolean =>
     gSignalHandlerIsConnected(getHandle(instance), handlerId) as boolean;
 
+const trackConnection = (instance: object, signal: string, handlerId: number): void => {
+    let bySignal = connectionTable.get(instance);
+
+    if (!bySignal) {
+        bySignal = new Map();
+        connectionTable.set(instance, bySignal);
+    }
+
+    let handlerIds = bySignal.get(signal);
+
+    if (!handlerIds) {
+        handlerIds = new Set();
+        bySignal.set(signal, handlerIds);
+    }
+
+    handlerIds.add(handlerId);
+};
+
+const untrackConnection = (instance: object, handlerId: number): void => {
+    const bySignal = connectionTable.get(instance);
+
+    if (bySignal === undefined) {
+        return;
+    }
+
+    for (const [name, handlerIds] of bySignal) {
+        handlerIds.delete(handlerId);
+
+        if (handlerIds.size === 0) {
+            bySignal.delete(name);
+        }
+    }
+};
+
+/**
+ * Disconnects the handler an instance connected under the given id, and forgets the connection.
+ * @param instance Emitter the handler was connected to.
+ * @param handlerId Id {@link connectSignal} returned for the handler.
+ */
+const disconnectSignal = (instance: object, handlerId: number): void => {
+    untrackConnection(instance, handlerId);
+    gSignalHandlerDisconnect(getHandle(instance), handlerId);
+};
+
+const hasLiveConnection = (instance: object, handlerIds: Set<number>): boolean => {
+    let isLive = false;
+
+    for (const handlerId of handlerIds) {
+        if (isSignalHandlerConnected(instance, handlerId)) {
+            isLive = true;
+        } else {
+            handlerIds.delete(handlerId);
+        }
+    }
+
+    return isLive;
+};
+
+function hasSignalListener(instance: object, signals?: string[]): boolean {
+    const bySignal = connectionTable.get(instance);
+
+    if (!bySignal) {
+        return false;
+    }
+
+    const names =
+        signals === undefined ? bySignal.keys().toArray() : signals.map((signal) => getSignalBaseName(signal));
+
+    return names.some((name) => {
+        const handlerIds = bySignal.get(name);
+
+        return handlerIds !== undefined && hasLiveConnection(instance, handlerIds);
+    });
+}
+
 const getSignalId = (instance: object, signal: string): number => {
     const type: bigint = (instance as TypedClass).__type__;
 
@@ -123,16 +199,13 @@ 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;
+    trackConnection(instance, getSignalBaseName(signal), handlerId);
 
-    return connect(getHandle(instance), signal, wrapped, isAfter ? 1 : 0) as number;
-}
-
-function blockMatchedSignalHandlers(instance: object, signal: string): void {
-    const signalId = getSignalId(instance, signal);
-    gSignalHandlersBlockMatched(getHandle(instance), 1, signalId, 0, undefined, undefined, undefined);
+    return handlerId;
 }
 
 const createEmitValue = (arg: EmitArg): { value: ExternalObject<Handle>; read?: () => unknown } => {
@@ -153,54 +226,55 @@ 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)[] = [];
+    const { values, reads } = collectEmitValues(instance, args);
 
-    for (const arg of args) {
-        const { value, read } = createEmitValue(arg);
-        values.push(value);
+    if (returns === undefined) {
+        gSignalEmitv(values, signalId, detail, undefined);
 
-        if (read) {
-            reads.push(read);
-        }
+        return packTupleResult(readEmitOutputs(reads), undefined, false);
     }
 
-    if (returnDescriptor !== undefined) {
-        const returnValue = newValueForDescriptor(returnDescriptor);
-        gSignalEmitv(values, signalId, detail, returnValue);
+    const returnValue = newValueForDescriptor(returns);
+    gSignalEmitv(values, signalId, detail, returnValue);
 
-        return packTupleResult(
-            reads.map((read) => read()),
-            fromValue(returnValue),
-            true,
-        );
-    }
-
-    gSignalEmitv(values, signalId, detail, undefined);
-
-    return packTupleResult(
-        reads.map((read) => read()),
-        undefined,
-        false,
-    );
+    return packTupleResult(readEmitOutputs(reads), fromValue(returnValue), true);
 }
 
 export {
     getSignalBaseName,
     connectSignal,
-    blockMatchedSignalHandlers,
+    disconnectSignal,
     emitSignal,
+    hasSignalListener,
     isSignalHandlerConnected,
+    untrackConnection,
     type SignalHandler,
 };

package/src/t.ts

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