@gtkx/runtime 1.6.0 → 2.0.0-beta.1

package/src/descriptors.ts

@@ -36,12 +36,7 @@ type StringDescriptor = Extract<Descriptor, { kind: "string" }>;
 
 /** Descriptor variant for a `GObject`, extended with the statically declared type of its value. */
 type ObjectDescriptor = Extract<Descriptor, { kind: "object" }> & {
-    /**
-     * Returns the wrapper class of the value's declared type. Referencing the class here keeps it
-     * in a tree-shaken bundle; the registry is still consulted first, so the thunk only decides
-     * the wrapper when no class is registered for the value's runtime type or an ancestor below
-     * the declared one.
-     */
+    /** Retains and supplies the declared wrapper when no more-derived wrapper is registered. */
     fallbackClass?: () => AnyClass;
 };
 
@@ -54,10 +49,7 @@ type BufferDescriptor = Extract<Descriptor, { kind: "buffer" }>;
 
 /** Descriptor variant for a `GBoxed` value, extended with the statically declared type of its value. */
 type BoxedDescriptor = Extract<Descriptor, { kind: "boxed" }> & {
-    /**
-     * Returns the wrapper class of the value's declared type, used when no class is registered
-     * for the boxed GType. Referencing the class here keeps it in a tree-shaken bundle.
-     */
+    /** Retains and supplies the declared wrapper when none is registered. */
     fallbackClass?: () => AnyClass;
 };
 
@@ -71,12 +63,7 @@ type StructDescriptor = Extract<Descriptor, { kind: "struct" }> & {
 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;
-    /**
-     * Returns the wrapper class of the value's declared type, used when no class is registered
-     * for the value's runtime type or an ancestor. Referencing the class here keeps it in a
-     * tree-shaken bundle. Unlike `wrapperClass`, the registry is consulted first, so a value of
-     * a more derived registered type keeps its own wrapper.
-     */
+    /** Retains and supplies the declared wrapper after checking the runtime-type registry. */
     fallbackClass?: () => AnyClass;
 };
 
@@ -115,10 +102,7 @@ type BoxedOptions = {
     fallbackClass?: () => AnyClass;
 };
 
-/**
- * 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.
- */
+/** Callback result, closure ownership, and lifetime options. */
 type CallbackOptions = {
     /** The callee also takes a destroy notify, which frees the closure once it is done with it. */
     hasDestroy?: boolean;
@@ -128,10 +112,7 @@ type CallbackOptions = {
     hasUserData?: boolean;
     /** Position of `user_data` among the callback's own arguments, dropped before the closure is called. */
     userDataIndex?: number;
-    /**
-     * The callback's C signature ends with a `GError**`, which receives a `GError` built from
-     * whatever the JavaScript function throws while the callback returns its failure value.
-     */
+    /** Converts a thrown value to the callback's trailing `GError**`. */
     canThrow?: boolean;
     /** Lifetime of the closure; defaults to `notified` when `hasDestroy` is set and `call` otherwise. */
     scope?: CallbackDescriptor["scope"];
@@ -149,12 +130,10 @@ type ArrayOptions = {
     fixedSize?: number | undefined;
     /** Whether the array carries raw bytes, and so decodes to a `Uint8Array` rather than to numbers. */
     isBytes?: boolean | undefined;
-    /**
-     * Whether the caller supplies the storage for a fixed-length out array: the runtime allocates
-     * a buffer of the element stride times the fixed element count, passes its pointer, and
-     * decodes the elements the callee wrote into it.
-     */
+    /** Allocates and decodes caller-owned storage for a fixed-length out array. */
     isCallerAllocated?: boolean | undefined;
+    /** Adds a zero element after the declared length. */
+    isZeroTerminated?: boolean | undefined;
 };
 
 /** Where a cursor array's base buffer and total length come from. */
@@ -197,6 +176,12 @@ type StructOptions = {
     size?: number;
     /** Class a decoded value is wrapped in, instead of the one registered for its GType. */
     wrapperClass?: AnyClass;
+    /** Library the struct's declared copy and free functions are resolved from; without it neither is used. */
+    sharedLibrary?: string;
+    /** Function duplicating an instance, used instead of a byte copy when the struct declares one. */
+    copyFnName?: string;
+    /** Function releasing an instance, used instead of `g_free` when the struct declares one. */
+    freeFnName?: string;
 };
 
 /** Descriptor for a `gint8`, marshalled as a number. */
@@ -238,20 +223,43 @@ const fundamentalLifecycles: Map<string, FundamentalLifecycle> = new Map();
 const isGtypeDescriptor = (descriptor: Descriptor): descriptor is TypeDescriptor =>
     descriptor.kind === "biguint64" && "type" in descriptor;
 
-/**
- * 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.
- * `fallbackClass` names the wrapper class of the declared type, retaining it in tree-shaken
- * bundles and wrapping the value in it when nothing at least as derived is registered.
- */
-const objectT = (ownership: Ownership = "borrowed", fallbackClass?: () => AnyClass): ObjectDescriptor =>
-    fallbackClass === undefined ? { kind: "object", ownership } : { kind: "object", ownership, fallbackClass };
+/** Builds a C-string descriptor, including optional buffer length and record-owned storage. */
+const stringT = (
+    ownership: Ownership = "borrowed",
+    length?: number,
+    hasOwnedStorage?: boolean,
+): StringDescriptor => {
+    const result: StringDescriptor = { kind: "string", ownership };
+
+    if (length !== undefined) {
+        result.length = length;
+    }
+
+    if (hasOwnedStorage === true) {
+        result.hasOwnedStorage = true;
+    }
+
+    return result;
+};
+
+/** Builds a runtime-typed `GObject` descriptor with an optional retained fallback class. */
+const objectT = (
+    ownership: Ownership = "borrowed",
+    fallbackClass?: () => AnyClass,
+    typeName?: string,
+): ObjectDescriptor => {
+    const result: ObjectDescriptor = { kind: "object", ownership };
+
+    if (fallbackClass !== undefined) {
+        result.fallbackClass = fallbackClass;
+    }
+
+    if (typeName !== undefined) {
+        result.typeName = typeName;
+    }
+
+    return result;
+};
 
 /** Wraps a descriptor in a pointer to it, for an output or inout argument. */
 const refT = (innerDescriptor: Descriptor, isInout = false): RefDescriptor =>
@@ -269,19 +277,28 @@ const hashTableT = (
     ownership,
 });
 
-/** Builds a descriptor for an enumeration, resolving its GType from the named `get_type` function. */
-const enumT = (sharedLibrary: string, typeFnName: string, isSigned: boolean): EnumDescriptor => ({
-    kind: "enum",
-    sharedLibrary,
-    getTypeFnName: typeFnName,
-    isSigned,
-});
+/** Builds an enum descriptor from a GType function or an explicit set of members. */
+const enumT = (
+    sharedLibrary: string,
+    typeFnName: string,
+    isSigned: boolean,
+    members?: number[],
+): EnumDescriptor => {
+    const result: EnumDescriptor = {
+        kind: "enum",
+        sharedLibrary,
+        getTypeFnName: typeFnName,
+        isSigned,
+    };
 
-/**
- * Builds a descriptor for a flags type, resolving its GType from the named `get_type` function.
- * For flags without a registered GType, pass empty library and function names and supply `mask`,
- * the union of all valid bits, which invalid combinations are rejected against.
- */
+    if (members !== undefined) {
+        result.members = members;
+    }
+
+    return result;
+};
+
+/** Builds a flags descriptor from a GType function or an explicit bit mask. */
 const flagsT = (sharedLibrary: string, typeFnName: string, isSigned: boolean, mask?: number): FlagsDescriptor => {
     const result: FlagsDescriptor = {
         kind: "flags",
@@ -344,6 +361,22 @@ const boxedT = (typeName: string, options: BoxedOptions = {}): BoxedDescriptor =
     return result;
 };
 
+const applyStructLifecycle = (result: StructDescriptor, options: StructOptions): void => {
+    if (options.sharedLibrary === undefined) {
+        return;
+    }
+
+    result.sharedLibrary = options.sharedLibrary;
+
+    if (options.copyFnName !== undefined) {
+        result.copyFnName = options.copyFnName;
+    }
+
+    if (options.freeFnName !== undefined) {
+        result.freeFnName = options.freeFnName;
+    }
+};
+
 /** Builds a descriptor for a plain C struct. */
 const structT = (ownership: Ownership = "borrowed", options: StructOptions = {}): StructDescriptor => {
     const result: StructDescriptor = { kind: "struct", ownership };
@@ -364,6 +397,8 @@ const structT = (ownership: Ownership = "borrowed", options: StructOptions = {})
         result.isInline = true;
     }
 
+    applyStructLifecycle(result, options);
+
     return result;
 };
 
@@ -455,6 +490,10 @@ const arrayT = (
         result.isCallerAllocated = true;
     }
 
+    if (options.isZeroTerminated === true) {
+        result.isZeroTerminated = true;
+    }
+
     return result;
 };
 
@@ -498,10 +537,7 @@ const sizedArrayT = (
     options: ArrayOptions = {},
 ): ArrayDescriptor => arrayT(itemDescriptor, "sized", ownership, { ...options, sizeParamIndex });
 
-/**
- * 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.
- */
+/** Builds an out-array cursor into another argument's buffer. */
 const cursorArrayT = (
     itemDescriptor: Descriptor,
     bounds: CursorBounds,

package/src/fn.ts

@@ -158,12 +158,33 @@ const isPassThroughPlan = (plan: ArgSpec, index: number): boolean =>
     !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 KINDS_PASSED_AS_POINTER: ReadonlySet<Descriptor["kind"]> = new Set<Descriptor["kind"]>([
+    "array",
+    "boxed",
+    "buffer",
+    "callback",
+    "fundamental",
+    "hashtable",
+    "object",
+    "string",
+    "struct",
+]);
+
+type RequiredInput = {
+    index: number;
+    rejectsNull: boolean;
+};
+
+const requiredInputs = (plans: ArgSpec[]): RequiredInput[] =>
+    plans
+        .filter((plan) => plan.requiresInput && plan.arg.isRequired === true)
+        .map((plan) => ({ index: plan.inputIndex, rejectsNull: KINDS_PASSED_AS_POINTER.has(plan.arg.type.kind) }));
+
+const assertRequiredInputs = (required: RequiredInput[], inputs: unknown[]): void => {
+    for (const { index, rejectsNull } of required) {
+        const input = inputs[index];
 
-const assertRequiredInputs = (requiredIndices: number[], inputs: unknown[]): void => {
-    for (const index of requiredIndices) {
-        if (inputs[index] === undefined) {
+        if (input === undefined || (rejectsNull && input === null)) {
             throw new TypeError(`Missing required argument at position ${String(index + 1)}`);
         }
     }
@@ -193,10 +214,10 @@ const directCallable = (
     plans: ArgSpec[],
 ): ((...inputs: unknown[]) => unknown) => {
     const argCount = plans.length;
-    const requiredIndices = requiredInputIndices(plans);
+    const required = requiredInputs(plans);
 
     const marshal = (inputs: unknown[]): unknown => {
-        assertRequiredInputs(requiredIndices, inputs);
+        assertRequiredInputs(required, inputs);
 
         return readReturn(call(descriptor, resizeInputs(inputs, argCount)));
     };
@@ -226,14 +247,14 @@ function fromNativeCallable(
         return directCallable(descriptor, readReturn, hasPrimary, plans);
     }
 
-    const requiredIndices = requiredInputIndices(plans);
+    const required = requiredInputs(plans);
 
     const shape = (inputs: unknown[], nativeValues: unknown[], nativeResult: unknown): unknown =>
         packTupleResult(readOutParams(outPlans, inputs, nativeValues), readReturn(nativeResult), hasPrimary);
 
     if (canThrow) {
         return (...inputs) => {
-            assertRequiredInputs(requiredIndices, inputs);
+            assertRequiredInputs(required, inputs);
             const nativeValues = buildNativeValues(plans, inputs, getRefSeeds?.());
             const errorRef: Ref = { value: null };
             nativeValues.push(errorRef);
@@ -245,7 +266,7 @@ function fromNativeCallable(
     }
 
     return (...inputs) => {
-        assertRequiredInputs(requiredIndices, inputs);
+        assertRequiredInputs(required, inputs);
         const nativeValues = buildNativeValues(plans, inputs, getRefSeeds?.());
 
         return shape(inputs, nativeValues, call(descriptor, nativeValues));

package/src/folded-lengths.ts

@@ -28,15 +28,7 @@ const addLengthSource = (sources: LengthSources, index: number | undefined, sour
         return;
     }
 
-    const existing = sources.get(index);
-
-    if (existing === undefined) {
-        sources.set(index, [source]);
-
-        return;
-    }
-
-    existing.push(source);
+    sources.getOrInsertComputed(index, () => []).push(source);
 };
 
 const addOutArgLengthSources = (sources: LengthSources, spec: FoldedLengthSpec): void => {
@@ -52,6 +44,27 @@ const addOutArgLengthSources = (sources: LengthSources, spec: FoldedLengthSpec):
     }
 };
 
+const foldedLengthArgIndices = (spec: FoldedLengthSpec): ReadonlySet<number> => {
+    const indices: Set<number> = new Set();
+
+    const add = (declaredIndex: number | undefined): void => {
+        const argIndex = effectiveArgIndex(declaredIndex, spec.userDataIndex);
+
+        if (argIndex !== undefined) {
+            indices.add(argIndex);
+        }
+    };
+
+    add(sizedArrayLengthIndex(spec.returnDescriptor));
+
+    for (const descriptor of spec.argDescriptors) {
+        add(sizedArrayLengthIndex(descriptor));
+        add(outArgLengthIndex(descriptor));
+    }
+
+    return indices;
+};
+
 const foldedLengthSources = (spec: FoldedLengthSpec): LengthSources => {
     const sources: LengthSources = new Map();
     const returnLengthIndex = effectiveArgIndex(sizedArrayLengthIndex(spec.returnDescriptor), spec.userDataIndex);
@@ -61,4 +74,4 @@ const foldedLengthSources = (spec: FoldedLengthSpec): LengthSources => {
     return sources;
 };
 
-export { foldedLengthSources, type LengthSource, type LengthSources };
+export { foldedLengthArgIndices, foldedLengthSources, type LengthSource, type LengthSources };

package/src/index.ts

@@ -1,22 +1,14 @@
 import "./exit-hook.js";
 
-/** @public */
 export { type ApplicationClass, type CommandLineApplication, createApplication } from "./application-class.js";
-/** @public */
+export { CallbackMarshalError } from "./callback.js";
 export { type ClosureCallback, ClosureMarshalError, toClosure, tryToClosure } from "./closure.js";
-/** @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";
-/** @public */
 export { installMixins, type Mixin } from "./mixin.js";
-/** @public */
-export { fromNative, toNative } from "./native-value.js";
-/** @public */
+export { fromNative, toHashTableEntries, toNative } from "./native-value.js";
 export {
     type ConstructBinding,
     type ConstructBindings,
@@ -25,22 +17,16 @@ export {
     registerConstructProperties,
     setObjectProperty,
 } from "./object.js";
-/** @public */
 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, type SignalGType, type SignalSpec } from "./register-class.js";
-/** @public */
 export {
     getClassType,
     getHandle,
@@ -58,7 +44,6 @@ export {
     type WrapperClass,
     type WrapperClassResolver,
 } from "./registry.js";
-/** @public */
 export {
     connectSignal,
     disconnectSignal,
@@ -67,9 +52,7 @@ export {
     type SignalHandler,
     signalForHandlerName,
 } from "./signal.js";
-/** @public */
 export { t } from "./t.js";
-/** @public */
 export {
     resolveType,
     TYPE_BOOLEAN,
@@ -105,7 +88,6 @@ export {
     typeParent,
     valueIsA,
 } from "./type.js";
-/** @public */
 export {
     fromValue,
     getBoxedValue,
@@ -115,7 +97,6 @@ export {
     tryToValueHandle,
     ValueMarshalError,
 } from "./value.js";
-/** @public */
 export {
     type ByteArray,
     type FromVariantOptions,
@@ -126,9 +107,6 @@ export {
     type VariantInput,
     type VariantValue,
 } from "./variant.js";
-/** @public */
 export { callParent, callVfunc } from "./vfunc-call.js";
-/** @public */
 export { alloc, type ExternalObject, type Handle, read, write } from "@gtkx/native";
-/** @public */
 export { type AnyClass } from "@gtkx/utils";

package/src/internal.ts

@@ -5,9 +5,9 @@ export {
     registeredElementProperties,
     registeredElementSignals,
 } from "./element-metadata.js";
-export { checkError, createErrorDomain } from "./error.js";
+export { createErrorDomain } from "./error.js";
 export { type ApplicationInstance, getApplicationInstance } from "./lifecycle.js";
-export { getExactWrapperClass, registerClassType, resolveWrapperClass, wrapHandle } from "./registry.js";
+export { getExactWrapperClass, resolveWrapperClass } from "./registry.js";
 export { hasSignalListener } from "./signal.js";
 export { resolveType } from "./type.js";
 export {

package/src/native-value.ts

@@ -255,12 +255,33 @@ function collectionToNative(descriptor: ArrayDescriptor, value: unknown): unknow
     return value == null ? null : mapCollection(descriptor, value, toNative);
 }
 
-function hashTableToNative(descriptor: HashTableDescriptor, value: unknown): unknown {
+/**
+ * Normalises the JavaScript form of a hash table argument into its entry list. A `Map` is the
+ * expected form and any other iterable of pairs is accepted; anything else is rejected, a plain
+ * object above all, which `Array.from` would quietly flatten into an empty table.
+ *
+ * @param value The JavaScript value passed for a hash table argument.
+ */
+function toHashTableEntries(value: unknown): [unknown, unknown][] | null {
     if (value == null) {
         return null;
     }
 
-    return [...(value as Map<unknown, unknown>)].map(([key, val]): [unknown, unknown] => [
+    if (typeof (value as Partial<Iterable<unknown>>)[Symbol.iterator] !== "function") {
+        throw new TypeError("A hash table argument must be a Map or an iterable of [key, value] pairs");
+    }
+
+    return [...(value as Iterable<[unknown, unknown]>)];
+}
+
+function hashTableToNative(descriptor: HashTableDescriptor, value: unknown): unknown {
+    const entries = toHashTableEntries(value);
+
+    if (entries === null) {
+        return null;
+    }
+
+    return entries.map(([key, val]): [unknown, unknown] => [
         toNative(descriptor.keyDescriptor, key),
         toNative(descriptor.valueDescriptor, val),
     ]);
@@ -302,4 +323,4 @@ function toNative(descriptor: Descriptor, value: unknown): unknown {
     }
 }
 
-export { fromNative, toNative };
+export { fromNative, toHashTableEntries, toNative };

package/src/properties.ts

@@ -1,6 +1,5 @@
 import type { ExternalObject, Handle, RegisterClassProperty } from "@gtkx/native";
-import type { AnyClass } from "@gtkx/utils";
-import { camelCase, kebabCase, toCamelIdentifier } from "@gtkx/utils";
+import { type AnyClass, camelCase, kebabCase, toCamelIdentifier } from "@gtkx/utils";
 import { bind } from "./bind.js";
 import { biguint64T, fundamentalT, refT, sizedArrayT, stringT, structT, uint32T, voidT } from "./descriptors.js";
 import { LIB, PARAM_T, VALUE_T } from "./library.js";
@@ -347,21 +346,9 @@ function lookupCoercionCheck(gtype: bigint, name: string): PropertyCheck | null
 }
 
 function coercionCheckFor(gtype: bigint, name: string): PropertyCheck | null {
-    let checks = coercionChecks.get(gtype);
+    const checks = coercionChecks.getOrInsertComputed(gtype, () => new Map<string, PropertyCheck | null>());
 
-    if (checks === undefined) {
-        checks = new Map();
-        coercionChecks.set(gtype, checks);
-    }
-
-    let check = checks.get(name);
-
-    if (check === undefined) {
-        check = lookupCoercionCheck(gtype, name);
-        checks.set(name, check);
-    }
-
-    return check;
+    return checks.getOrInsertComputed(name, () => lookupCoercionCheck(gtype, name));
 }
 
 function truncateToWhole(check: PropertyCheck, value: number): number {