@gtkx/runtime 1.2.2 → 1.4.0

package/src/value.ts

@@ -7,6 +7,7 @@ import {
     biguint64T,
     booleanT,
     boxedT,
+    byteArrayT,
     float32T,
     float64T,
     type FundamentalDescriptor,
@@ -23,8 +24,27 @@ import {
 } from "./descriptors.js";
 import { LIB, PARAM_T, VALUE_SIZE, VALUE_T, VARIANT_T } from "./library.js";
 import { toNative } from "./native-value.js";
-import { getHandle, getWrapperClass, wrapHandle, wrapObject } from "./registry.js";
 import {
+    INT32_MAXIMUM,
+    INT32_MINIMUM,
+    INT64_MAXIMUM,
+    INT64_MINIMUM,
+    isStringArray,
+    resolveGtype,
+    UINT64_MAXIMUM,
+    type ValueGuard,
+} from "./param-spec.js";
+import {
+    coerceGType,
+    describeValueKind,
+    getHandle,
+    getWrapperClass,
+    wrapFundamentalHandle,
+    wrapHandle,
+    wrapObject,
+} from "./registry.js";
+import {
+    getByteArrayType,
     getStrvType,
     isResolvableDescriptor,
     resolveBoxedType,
@@ -53,7 +73,9 @@ import {
     TYPE_UINT64,
     TYPE_ULONG,
     TYPE_VARIANT,
+    type TypedClass,
     typeFundamental,
+    typeIsA,
     typeName,
 } from "./type.js";
 
@@ -65,6 +87,15 @@ type ValueType = {
 type ValueGetter = (value: ExternalObject<Handle>) => unknown;
 type ValueWriter = ValueType["set"];
 type ValueNarrower = (jsValue: unknown) => unknown;
+/**
+ * JavaScript value a `GObject.Value` can be built from without being told which GType to hold, for the
+ * parameters that take one. A string holds `gchararray`, a boolean `gboolean`, an integer within `gint`
+ * range `gint` and any other number `gdouble`, a `bigint` `gint64` or `guint64` past its range, an array
+ * of strings `GStrv`, a wrapper instance the GType it carries, and `null` a NULL `gpointer`, which is
+ * what GJS infers for it and which few callees accept. Reaching a GType inference cannot name, such as
+ * `guchar` or an enumeration, takes an explicitly initialized `GObject.Value` instead.
+ */
+type JsValue = string | number | bigint | boolean | string[] | TypedClass | null;
 
 const setBoxedCache = createBindCache();
 const setStaticBoxedCache = createBindCache();
@@ -74,7 +105,15 @@ 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);
-const typeValueType = bindValueType("gtype", biguint64T);
+const boundTypeValueType = bindValueType("gtype", biguint64T);
+
+const typeValueType: ValueType = {
+    set: (value, jsValue) => {
+        boundTypeValueType.set(value, coerceGType(jsValue));
+    },
+    get: boundTypeValueType.get,
+};
+
 const scharValueType = bindValueType("schar", int8T);
 const ucharValueType = bindValueType("uchar", uint8T);
 const intValueType = bindValueType("int", int32T);
@@ -99,6 +138,11 @@ const strvValueType: ValueType = {
     get: bind(LIB, "g_value_get_boxed", [VALUE_T], arrayT(stringT("borrowed"))),
 };
 
+const setByteArrayBoxed = bind(LIB, "g_value_set_boxed", [VALUE_T, byteArrayT()], voidT);
+const getBoxedPointer = bind(LIB, "g_value_get_boxed", [VALUE_T], uint64T);
+const getBytesBoxed = bind(LIB, "g_value_get_boxed", [VALUE_T], byteArrayT());
+const getByteItemsBoxed = bind(LIB, "g_value_get_boxed", [VALUE_T], arrayT(uint8T, "gbytearray"));
+
 const PLAIN_VALUE_TYPES: Partial<Record<Descriptor["kind"], ValueType>> = {
     boolean: booleanValueType,
     string: stringValueType,
@@ -117,6 +161,19 @@ const PLAIN_VALUE_TYPES: Partial<Record<Descriptor["kind"], ValueType>> = {
     object: objectValueType,
 };
 
+const WHOLE_NUMBER_KINDS: Set<Descriptor["kind"]> = new Set([
+    "int8",
+    "int16",
+    "int32",
+    "uint8",
+    "uint16",
+    "uint32",
+    "int64",
+    "uint64",
+    "enum",
+    "flags",
+]);
+
 const PLAIN_VALUE_GETTERS: Map<bigint, ValueGetter> = new Map([
     [TYPE_BOOLEAN, booleanValueType.get],
     [TYPE_CHAR, scharValueType.get],
@@ -184,6 +241,20 @@ const boxedValueType = (type: bigint): ValueType => {
     return { set: setBoxedBind(name), get: dupBoxedBind(name) };
 };
 
+const byteArrayValueGetterFor = (isBytes: boolean): ValueGetter => {
+    const get = isBytes ? getBytesBoxed : getByteItemsBoxed;
+
+    return (value) => (getBoxedPointer(value) ? get(value) : null);
+};
+
+const byteArrayValueType = (descriptor: ArrayDescriptor): ValueType => ({
+    set: setByteArrayValue,
+    get: byteArrayValueGetterFor(descriptor.isBytes === true),
+});
+
+const isByteArraySource = (jsValue: unknown): jsValue is Uint8Array | number[] =>
+    jsValue instanceof Uint8Array || Array.isArray(jsValue);
+
 const enumOrFlagsValueType = (type: bigint): ValueType =>
     typeFundamental(type) === TYPE_FLAGS ? flagsValueType : enumValueType;
 
@@ -277,7 +348,8 @@ const newBoxedValue = (
 
 /**
  * Duplicates the boxed value held by a GValue and returns the copy wrapped in the
- * class registered for its GType, or null when the GValue holds no boxed type.
+ * class its GType resolves to, or null when the GValue holds no boxed type.
+ * A `GByteArray` payload is copied into a `Uint8Array` instead of being wrapped.
  */
 function getBoxedValue(value: ExternalObject<Handle>): object | null {
     const type = getValueType(value);
@@ -286,16 +358,54 @@ function getBoxedValue(value: ExternalObject<Handle>): object | null {
         return null;
     }
 
-    const cls = getWrapperClass(type);
+    if (type === getByteArrayType()) {
+        return byteArrayValueGetterFor(true)(value) as Uint8Array | null;
+    }
+
     const boxed = dupBoxedBind(getBoxedTypeName(type))(value) as ExternalObject<Handle> | null;
 
-    return wrapHandle(boxed, cls);
+    if (boxed === null) {
+        return null;
+    }
+
+    return wrapHandle(boxed, getWrapperClass(type));
 }
 
-/** Stores a boxed object, or null, into a GValue that holds a boxed type. */
-function setBoxedValue(value: ExternalObject<Handle>, boxed: object | null): void {
-    const name = getBoxedTypeName(getValueType(value));
-    setBoxedBind(name)(value, boxed === null ? null : getHandle(boxed));
+/**
+ * Stores a boxed object, or null, into a GValue that holds a boxed type. A GValue holding
+ * `G_TYPE_VALUE` also takes any other {@link JsValue}, which is boxed into a nested `GObject.Value`
+ * of the GType inferred from it, and one holding a `GByteArray` also takes the bytes as a
+ * `Uint8Array` or an array of byte values.
+ * @param value Handle of an initialized value to write into.
+ * @param boxed The boxed instance, bytes, or {@link JsValue} to store.
+ * @throws {ValueMarshalError} When the value cannot hold what was passed.
+ */
+function setBoxedValue(value: ExternalObject<Handle>, boxed: JsValue | object): void {
+    const type = getValueType(value);
+
+    if (type === resolveBoxedType(VALUE_T)) {
+        setBoxedBind("GValue")(value, boxed === null ? null : toValueHandle(boxed));
+
+        return;
+    }
+
+    if (type === getByteArrayType() && isByteArraySource(boxed)) {
+        setByteArrayBoxed(value, boxed);
+
+        return;
+    }
+
+    setWrappedBoxedValue(value, type, boxed);
+}
+
+function setWrappedBoxedValue(value: ExternalObject<Handle>, type: bigint, boxed: JsValue | object): void {
+    if (boxed !== null && typeof boxed !== "object") {
+        throw new ValueMarshalError(
+            `Cannot marshal ${describeValueKind(boxed)} into a '${getBoxedTypeName(type)}' value`,
+        );
+    }
+
+    setBoxedBind(getBoxedTypeName(type))(value, boxed === null ? null : getHandle(boxed));
 }
 
 const arrayValueType = (descriptor: ArrayDescriptor): ValueType => {
@@ -303,6 +413,10 @@ const arrayValueType = (descriptor: ArrayDescriptor): ValueType => {
         return strvValueType;
     }
 
+    if (descriptor.arrayKind === "gbytearray") {
+        return byteArrayValueType(descriptor);
+    }
+
     throw new Error(`Unsupported array type ${descriptor.arrayKind} of ${descriptor.itemDescriptor.kind}`);
 };
 
@@ -349,11 +463,17 @@ const wrappedValueGetter = (fundamental: bigint): ValueGetter | undefined => {
         }
         case TYPE_PARAM: {
             return (value) =>
-                wrapHandle(paramValueType.get(value) as ExternalObject<Handle> | null, getWrapperClass(TYPE_PARAM));
+                wrapFundamentalHandle(
+                    paramValueType.get(value) as ExternalObject<Handle> | null,
+                    getWrapperClass(TYPE_PARAM),
+                );
         }
         case TYPE_VARIANT: {
             return (value) =>
-                wrapHandle(variantValueType.get(value) as ExternalObject<Handle> | null, getWrapperClass(TYPE_VARIANT));
+                wrapFundamentalHandle(
+                    variantValueType.get(value) as ExternalObject<Handle> | null,
+                    getWrapperClass(TYPE_VARIANT),
+                );
         }
         case TYPE_BOXED: {
             return getBoxedValue;
@@ -381,6 +501,10 @@ function setStrvValue(value: ExternalObject<Handle>, nativeValue: unknown): void
     setStrvBoxed(value, nativeValue ?? null);
 }
 
+function setByteArrayValue(value: ExternalObject<Handle>, nativeValue: unknown): void {
+    setByteArrayBoxed(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");
@@ -406,7 +530,8 @@ const customFundamentalGetter = (type: bigint): ValueGetter | undefined => {
         return undefined;
     }
 
-    return (value) => wrapHandle(valueType.get(value) as ExternalObject<Handle> | null, getWrapperClass(type));
+    return (value) =>
+        wrapFundamentalHandle(valueType.get(value) as ExternalObject<Handle> | null, getWrapperClass(type));
 };
 
 const customFundamentalSetter = (type: bigint): ValueType["set"] | undefined => {
@@ -456,6 +581,89 @@ function intoValue(value: ExternalObject<Handle>, jsValue: unknown): void {
     valueWriterFor(getValueType(value))(value, jsValue);
 }
 
+const numberValueGType = (jsValue: number): bigint =>
+    Number.isSafeInteger(jsValue) && jsValue >= INT32_MINIMUM && jsValue <= INT32_MAXIMUM ? TYPE_INT : TYPE_DOUBLE;
+
+const arrayValueGType = (jsValue: unknown[]): bigint => (isStringArray(jsValue) ? getStrvType() : TYPE_INVALID);
+const wideValueGType = (jsValue: bigint): bigint => (jsValue > INT64_MAXIMUM ? TYPE_UINT64 : TYPE_INT64);
+
+const bigintValueGType = (jsValue: bigint): bigint =>
+    jsValue < INT64_MINIMUM || jsValue > UINT64_MAXIMUM ? TYPE_INVALID : wideValueGType(jsValue);
+
+const objectValueGType = (jsValue: object | null, wrapperType: bigint): bigint => {
+    if (jsValue === null) {
+        return TYPE_POINTER;
+    }
+
+    return Array.isArray(jsValue) ? arrayValueGType(jsValue) : wrapperType;
+};
+
+function inferValueGType(jsValue: unknown, wrapperType: bigint): bigint {
+    switch (typeof jsValue) {
+        case "string": {
+            return TYPE_STRING;
+        }
+        case "boolean": {
+            return TYPE_BOOLEAN;
+        }
+        case "number": {
+            return numberValueGType(jsValue);
+        }
+        case "bigint": {
+            return bigintValueGType(jsValue);
+        }
+        case "object": {
+            return objectValueGType(jsValue, wrapperType);
+        }
+        case "function":
+        case "symbol":
+        case "undefined": {
+            return TYPE_INVALID;
+        }
+    }
+}
+
+const marshalFailure = (jsValue: unknown): string =>
+    typeof jsValue === "bigint"
+        ? `Cannot marshal ${String(jsValue)} into a GObject.Value: outside the range of gint64 and guint64`
+        : `Cannot marshal ${describeValueKind(jsValue)} into a GObject.Value`;
+
+const wrapperGType = (jsValue: unknown): bigint =>
+    typeof jsValue === "object" && jsValue !== null ? resolveGtype(jsValue) : TYPE_INVALID;
+
+/**
+ * Marshals a value passed where a `GObject.Value` is expected into a value handle: an already-built
+ * value yields its own handle, and any other {@link JsValue} is stored in a new one initialized to the
+ * GType inferred from it.
+ * @param jsValue Value to store, or an already-built `GObject.Value`.
+ * @throws {ValueMarshalError} When no GType can be inferred from the value.
+ */
+function toValueHandle(jsValue: unknown): ExternalObject<Handle> {
+    const wrapperType = wrapperGType(jsValue);
+
+    if (typeIsA(wrapperType, resolveBoxedType(VALUE_T))) {
+        return getHandle(jsValue as object);
+    }
+
+    const type = inferValueGType(jsValue, wrapperType);
+
+    if (type === TYPE_INVALID) {
+        throw new ValueMarshalError(marshalFailure(jsValue));
+    }
+
+    const value = newValueForType(type);
+    intoValue(value, jsValue);
+
+    return value;
+}
+
+/** Same as {@link toValueHandle}, but passes a null or undefined value through as no value at all. */
+const tryToValueHandle = (jsValue: unknown): ExternalObject<Handle> | undefined =>
+    jsValue == null ? undefined : toValueHandle(jsValue);
+
+const isValueDescriptor = (descriptor: Descriptor): boolean =>
+    descriptor.kind === "boxed" && descriptor.typeName === "GValue";
+
 const resolveNativeValue = (descriptor: Descriptor, value: unknown): unknown => {
     const isHandleKind = descriptor.kind === "object" || descriptor.kind === "boxed";
 
@@ -463,7 +671,11 @@ const resolveNativeValue = (descriptor: Descriptor, value: unknown): unknown =>
         return toNative(descriptor, value);
     }
 
-    return value == null ? null : getHandle(value);
+    if (value == null) {
+        return null;
+    }
+
+    return isValueDescriptor(descriptor) ? toValueHandle(value) : getHandle(value);
 };
 
 const resolveValueGType = (descriptor: Descriptor, nativeValue: unknown): bigint => {
@@ -474,8 +686,13 @@ const resolveValueGType = (descriptor: Descriptor, nativeValue: unknown): bigint
     return nativeValue == null ? TYPE_OBJECT : getType(nativeValue as ExternalObject<Handle>);
 };
 
+const toWholeNumber = (descriptor: Descriptor, value: unknown): unknown =>
+    typeof value === "number" && Number.isFinite(value) && WHOLE_NUMBER_KINDS.has(descriptor.kind)
+        ? Math.trunc(value)
+        : value;
+
 function toValue(descriptor: Descriptor, value: unknown): ExternalObject<Handle> {
-    const nativeValue = resolveNativeValue(descriptor, value);
+    const nativeValue = resolveNativeValue(descriptor, toWholeNumber(descriptor, value));
     const type = resolveValueGType(descriptor, nativeValue);
     const gValue = newValueForType(type);
     resolveValueType(descriptor).set(gValue, nativeValue);
@@ -483,6 +700,13 @@ function toValue(descriptor: Descriptor, value: unknown): ExternalObject<Handle>
     return gValue;
 }
 
+/**
+ * Reads what a `GObject.Value` holds as its JavaScript form, wrapping an object, boxed, param, variant,
+ * or fundamental payload in the class registered for its GType, and handing back a string, number,
+ * `bigint`, boolean, or array of strings for the rest.
+ * @param value Handle of an initialized value to read.
+ * @throws {Error} When the GType it holds has no JavaScript form, such as a non-null `gpointer`.
+ */
 function fromValue(value: ExternalObject<Handle>): unknown {
     const type = getValueType(value);
     const get = resolveValueGetter(type);
@@ -494,6 +718,24 @@ function fromValue(value: ExternalObject<Handle>): unknown {
     return get(value);
 }
 
+const fromValueForDescriptor = (descriptor: Descriptor, value: ExternalObject<Handle>): unknown =>
+    descriptor.kind === "array" && descriptor.arrayKind === "gbytearray"
+        ? byteArrayValueGetterFor(descriptor.isBytes === true)(value)
+        : fromValue(value);
+
+const inferredValueGuard: ValueGuard = (jsValue) => inferValueGType(jsValue, wrapperGType(jsValue)) !== TYPE_INVALID;
+
+const byteArrayValueGuard: ValueGuard = (jsValue) =>
+    jsValue == null || isByteArraySource(jsValue) || typeIsA(resolveGtype(jsValue), getByteArrayType());
+
+const valueGuardOverrideFor = (valueType: bigint): ValueGuard | undefined => {
+    if (valueType === resolveBoxedType(VALUE_T)) {
+        return inferredValueGuard;
+    }
+
+    return valueType === getByteArrayType() ? byteArrayValueGuard : undefined;
+};
+
 function newValueForDescriptor(descriptor: Descriptor): ExternalObject<Handle> {
     return newValueForType(resolveDescriptorType(descriptor));
 }
@@ -523,14 +765,26 @@ function inoutValueForBoxedDescriptor(descriptor: Descriptor, boxed: object): Ex
     return newBoxedValue(descriptor, boxed, setStaticBoxedBind);
 }
 
+/** Thrown when a value passed where a `GObject.Value` is expected holds no GType one can be built from. */
+class ValueMarshalError extends TypeError {
+    /** Name callers match on when the error is caught as a plain `TypeError`. */
+    public override name = "ValueMarshalError";
+}
+
 export {
     getValueType,
     intoValue,
     copyValue,
     getBoxedValue,
     setBoxedValue,
+    type JsValue,
     toValue,
+    toValueHandle,
+    tryToValueHandle,
+    ValueMarshalError,
     fromValue,
+    fromValueForDescriptor,
+    valueGuardOverrideFor,
     newValueForDescriptor,
     newValueForType,
     outValueForDescriptor,