@gtkx/runtime 1.0.0-rc.4 → 1.1.0

package/src/mixin.ts

@@ -1,4 +1,4 @@
-import type { AnyClass } from "@gtkx/utils";
+import { type AnyClass, getParentClass } from "@gtkx/utils";
 
 /**
  * The signal plumbing every base class passed to a {@link Mixin} provides, so mixed-in interface
@@ -76,4 +76,17 @@ function installMixins(target: AnyClass, mixins: Mixin[]): void {
     }
 }
 
-export { installMixins, type MixinReceiver, type Mixin };
+function dropLayerMembers(layer: AnyClass, names: Set<string>): void {
+    for (const name of names) {
+        Reflect.deleteProperty(layer.prototype, name);
+    }
+}
+
+function insertMixinLayer(target: AnyClass, mixin: Mixin, inheritedNames: Set<string>): void {
+    const layer = mixin(getParentClass(target) as AnyClass<MixinReceiver>);
+    dropLayerMembers(layer, inheritedNames);
+    Object.setPrototypeOf(target.prototype, layer.prototype);
+    Object.setPrototypeOf(target, layer);
+}
+
+export { insertMixinLayer, installMixins, type MixinReceiver, type Mixin };

package/src/native-value.ts

@@ -1,6 +1,6 @@
 import type { Descriptor, ExternalObject, Handle } from "@gtkx/native";
 import type { ArrayDescriptor, FundamentalDescriptor, HashTableDescriptor, StructDescriptor } from "./descriptors.js";
-import { getWrapperClass, tryGetHandle, wrapHandle } from "./registry.js";
+import { getHandle, getWrapperClass, wrapCallScopedObject, wrapHandle, wrapObject } from "./registry.js";
 import { resolveDescriptorType } from "./type.js";
 
 type MarshalledKind = "object" | "struct" | "boxed" | "fundamental" | "array" | "hashtable";
@@ -76,7 +76,7 @@ function fromNative(descriptor: Descriptor, value: unknown): unknown {
 
     switch (descriptor.kind) {
         case "object": {
-            return wrapHandle(value as ExternalObject<Handle> | null);
+            return descriptor.isCallScoped === true ? wrapCallScopedObject(value) : wrapObject(value);
         }
         case "struct": {
             return wrapHandle(value as ExternalObject<Handle> | null, (descriptor as StructDescriptor).wrapperClass);
@@ -129,7 +129,9 @@ function toNative(descriptor: Descriptor, value: unknown): unknown {
         case "struct":
         case "boxed":
         case "fundamental": {
-            return tryGetHandle(value as object | null | undefined) ?? null;
+            const instance = value as object | null | undefined;
+
+            return instance == null ? null : getHandle(instance);
         }
         case "array": {
             return collectionToNative(descriptor, value);

package/src/object.ts

@@ -1,21 +1,25 @@
-import type { Descriptor, ExternalObject, Handle } from "@gtkx/native";
+import { type Descriptor, type ExternalObject, type Handle, newObject } from "@gtkx/native";
+import { type AnyClass, getParentClass } from "@gtkx/utils";
 import { bind } from "./bind.js";
-import { biguint64T, objectT, sizedArrayT, stringT, uint32T, voidT } from "./descriptors.js";
-import { LIB, VALUE_SIZE, VALUE_T } from "./library.js";
-import { getHandle } from "./registry.js";
+import { objectT, stringT, voidT } from "./descriptors.js";
+import { LIB, VALUE_T } from "./library.js";
+import { type ConstructProperty, constructPropertyFor } from "./properties.js";
+import { getHandle, registerWrapper } from "./registry.js";
 import { fromValue, newValueForDescriptor, toValue } from "./value.js";
 
-const gObjectNewWithProperties = bind(
-    LIB,
-    "g_object_new_with_properties",
-    [
-        biguint64T,
-        uint32T,
-        sizedArrayT(stringT("borrowed"), 1, "borrowed"),
-        sizedArrayT(VALUE_T, 1, "borrowed", VALUE_SIZE),
-    ],
-    objectT("full"),
-);
+/**
+ * One construct property a wrapper class accepts: the canonical `GObject` name it is set under,
+ * and the descriptor its value is marshalled through.
+ */
+type ConstructBinding = [name: string, descriptor: Descriptor];
+/** The construct properties a wrapper class accepts, keyed by the camelCased name callers give them. */
+type ConstructBindings = Record<string, ConstructBinding>;
+type ResolvedBindings = { generation: number; bindings: ConstructBindings };
+
+const declaredBindings: WeakMap<AnyClass, ConstructBindings> = new WeakMap();
+const resolvedBindings: WeakMap<AnyClass, ResolvedBindings> = new WeakMap();
+const declarations = { generation: 0 };
+const NO_BINDINGS: ConstructBindings = Object.create(null) as ConstructBindings;
 
 const gObjectGetProperty = bind(
     LIB,
@@ -31,37 +35,122 @@ const gObjectSetProperty = bind(
     voidT,
 );
 
+function collectDeclaredBindings(cls: AnyClass): ConstructBindings[] {
+    const declared: ConstructBindings[] = [];
+    let current: AnyClass | null = cls;
+
+    while (current !== null) {
+        const own = declaredBindings.get(current);
+
+        if (own !== undefined) {
+            declared.push(own);
+        }
+
+        current = getParentClass(current);
+    }
+
+    return declared;
+}
+
+function mergeDeclaredBindings(cls: AnyClass): ConstructBindings {
+    const declared = collectDeclaredBindings(cls);
+    const merged: ConstructBindings = Object.create(null) as ConstructBindings;
+
+    for (let index = declared.length - 1; index >= 0; index--) {
+        Object.assign(merged, declared[index]);
+    }
+
+    return merged;
+}
+
+function constructBindingsFor(cls: AnyClass | undefined): ConstructBindings {
+    if (cls === undefined) {
+        return NO_BINDINGS;
+    }
+
+    const cached = resolvedBindings.get(cls);
+
+    if (cached?.generation === declarations.generation) {
+        return cached.bindings;
+    }
+
+    const bindings = mergeDeclaredBindings(cls);
+    resolvedBindings.set(cls, { generation: declarations.generation, bindings });
+
+    return bindings;
+}
+
+/**
+ * Declares the construct properties a wrapper class accepts, so `newObjectWithProperties`
+ * marshals each one through its descriptor rather than resolving it from the
+ * `GObject.ParamSpec` the type installs. A class inherits the declarations of its ancestors.
+ * Registering takes effect immediately, including for classes already constructed from and for
+ * subclasses that already inherited an earlier declaration.
+ *
+ * @param cls The wrapper class the properties are declared on.
+ * @param bindings CamelCased property names mapped to their canonical name and descriptor.
+ */
+function registerConstructProperties(cls: AnyClass, bindings: ConstructBindings): void {
+    declaredBindings.set(cls, bindings);
+    declarations.generation += 1;
+}
+
+function constructPropertyForEntry(
+    source: { gtype: bigint; bindings: ConstructBindings; wrapper: object },
+    name: string,
+    value: unknown,
+): ConstructProperty | undefined {
+    if (value === undefined) {
+        return undefined;
+    }
+
+    const binding = source.bindings[name];
+
+    if (binding === undefined) {
+        return constructPropertyFor(source.gtype, name, value, source.wrapper);
+    }
+
+    return { name: binding[0], value: toValue(binding[1], value) };
+}
+
 /**
  * Constructs a new GObject of the given type, setting the supplied construct
- * properties. Entries whose value is `undefined` or not a `[descriptor, value]`
- * pair are skipped.
+ * properties, and binds `wrapper` to it. A property the wrapper's class declares
+ * through `registerConstructProperties` is marshalled through its descriptor; any
+ * other one is marshalled through the `GObject.ParamSpec` the type installs under
+ * that name, dashed or camelCased, and is skipped when the type installs none.
+ * A value that ParamSpec would refuse throws before GObject sees it: a `TypeError`
+ * 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.
+ * 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.
  *
  * @param gtype The GType of the object to construct.
- * @param props Property names mapped to `[descriptor, value]` pairs.
+ * @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.
  */
-function newObjectWithProperties(gtype: bigint, props: Record<string, unknown>): ExternalObject<Handle> {
+function newObjectWithProperties(gtype: bigint, props: object, wrapper: object): ExternalObject<Handle> {
     const names: string[] = [];
     const values: ExternalObject<Handle>[] = [];
+    const bindings = constructBindingsFor(wrapper.constructor as AnyClass | undefined);
+    const source = { gtype, bindings, wrapper };
 
-    for (const name in props) {
-        const entry: unknown = props[name];
+    for (const name of Object.keys(props)) {
+        const property = constructPropertyForEntry(source, name, Reflect.get(props, name));
 
-        if (!Array.isArray(entry)) {
-            continue;
+        if (property !== undefined) {
+            names.push(property.name);
+            values.push(property.value);
         }
-
-        const [descriptor, value] = entry as [Descriptor, unknown];
-
-        if (value === undefined) {
-            continue;
-        }
-
-        names.push(name);
-        values.push(toValue(descriptor, value));
     }
 
-    return gObjectNewWithProperties(gtype, names.length, names, values) as ExternalObject<Handle>;
+    newObject(gtype, names, values, wrapper, registerWrapper);
+
+    return getHandle(wrapper);
 }
 
 /**
@@ -81,7 +170,10 @@ function getObjectProperty(obj: object, propertyName: string, descriptor: Descri
 
 /**
  * Writes a JavaScript value to a GObject property, converting it to native form
- * using the descriptor.
+ * 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`.
  *
  * @param obj The object to write to.
  * @param propertyName The property name.
@@ -92,4 +184,11 @@ function setObjectProperty(obj: object, propertyName: string, descriptor: Descri
     gObjectSetProperty(getHandle(obj), propertyName, toValue(descriptor, jsValue));
 }
 
-export { newObjectWithProperties, getObjectProperty, setObjectProperty };
+export {
+    newObjectWithProperties,
+    getObjectProperty,
+    registerConstructProperties,
+    setObjectProperty,
+    type ConstructBinding,
+    type ConstructBindings,
+};

package/src/param-spec.ts

@@ -0,0 +1,234 @@
+import { type ExternalObject, type Handle, read } from "@gtkx/native";
+import { bind } from "./bind.js";
+import { biguint64T, booleanT, stringT, uint32T, voidT } from "./descriptors.js";
+import { LIB, PARAM_T, VALUE_T } from "./library.js";
+import { getInstanceType } from "./registry.js";
+import {
+    getStrvType,
+    isTypedClass,
+    TYPE_BOOLEAN,
+    TYPE_BOXED,
+    TYPE_CHAR,
+    TYPE_DOUBLE,
+    TYPE_ENUM,
+    TYPE_FLAGS,
+    TYPE_FLOAT,
+    TYPE_GTYPE,
+    TYPE_INT,
+    TYPE_INT64,
+    TYPE_INTERFACE,
+    TYPE_INVALID,
+    TYPE_LONG,
+    TYPE_OBJECT,
+    TYPE_PARAM,
+    TYPE_POINTER,
+    TYPE_STRING,
+    TYPE_UCHAR,
+    TYPE_UINT,
+    TYPE_UINT64,
+    TYPE_ULONG,
+    TYPE_VARIANT,
+    typeFundamental,
+    typeIsA,
+} from "./type.js";
+
+type ValueGuard = (value: unknown) => boolean;
+type ParamLayout = { flags: number; valueType: bigint };
+
+const PARAM_READABLE = 1;
+const PARAM_WRITABLE = 2;
+const PARAM_CONSTRUCT_ONLY = 8;
+const PARAM_LAX_VALIDATION = 16;
+const READ_FLAGS = PARAM_READABLE | PARAM_WRITABLE | PARAM_CONSTRUCT_ONLY | PARAM_LAX_VALIDATION;
+const FLAGS_BYTE_OFFSET = 16;
+const VALUE_TYPE_BYTE_OFFSET = 24;
+const LAYOUT_PROBE_NAME = "gtkx-param-layout";
+const INT8_MINIMUM = -128;
+const INT8_MAXIMUM = 127;
+const UINT8_MAXIMUM = 255;
+const INT32_MINIMUM = -2_147_483_648;
+const INT32_MAXIMUM = 2_147_483_647;
+const UINT32_MAXIMUM = 4_294_967_295;
+const INT64_MINIMUM = -(2n ** 63n);
+const INT64_MAXIMUM = 2n ** 63n - 1n;
+const UINT64_MAXIMUM = 2n ** 64n - 1n;
+
+const WRAPPED_FUNDAMENTALS: Set<bigint> = new Set([
+    TYPE_BOXED,
+    TYPE_INTERFACE,
+    TYPE_OBJECT,
+    TYPE_PARAM,
+    TYPE_VARIANT,
+]);
+
+const isWideUnsignedValue: ValueGuard = wideIntegerGuardFor(0n, UINT64_MAXIMUM);
+
+const SCALAR_GUARDS: Map<bigint, ValueGuard> = new Map([
+    [TYPE_BOOLEAN, isBooleanValue],
+    [TYPE_STRING, isStringValue],
+    [TYPE_CHAR, integerGuardFor(INT8_MINIMUM, INT8_MAXIMUM)],
+    [TYPE_UCHAR, integerGuardFor(0, UINT8_MAXIMUM)],
+    [TYPE_INT, integerGuardFor(INT32_MINIMUM, INT32_MAXIMUM)],
+    [TYPE_UINT, integerGuardFor(0, UINT32_MAXIMUM)],
+    [TYPE_ENUM, integerGuardFor(INT32_MINIMUM, INT32_MAXIMUM)],
+    [TYPE_FLAGS, integerGuardFor(0, UINT32_MAXIMUM)],
+    [TYPE_LONG, wideIntegerGuardFor(INT64_MINIMUM, INT64_MAXIMUM)],
+    [TYPE_ULONG, isWideUnsignedValue],
+    [TYPE_INT64, wideIntegerGuardFor(INT64_MINIMUM, INT64_MAXIMUM)],
+    [TYPE_UINT64, isWideUnsignedValue],
+    [TYPE_FLOAT, isNumberValue],
+    [TYPE_DOUBLE, isNumberValue],
+    [TYPE_POINTER, isNullValue],
+]);
+
+const layout = { wasChecked: false };
+const paramValueValidate = bind(LIB, "g_param_value_validate", [PARAM_T, VALUE_T], booleanT);
+const paramSpecUnref = bind(LIB, "g_param_spec_unref", [PARAM_T], voidT);
+const paramSpecRefSink = bind(LIB, "g_param_spec_ref_sink", [PARAM_T], PARAM_T);
+
+const newParamSpecBoolean = bind(
+    LIB,
+    "g_param_spec_boolean",
+    [stringT("borrowed"), stringT("borrowed"), stringT("borrowed"), booleanT, uint32T],
+    PARAM_T,
+);
+
+const getParamFlags = (pspec: ExternalObject<Handle>): number => read(pspec, uint32T, FLAGS_BYTE_OFFSET) as number;
+
+const getParamValueType = (pspec: ExternalObject<Handle>): bigint =>
+    read(pspec, biguint64T, VALUE_TYPE_BYTE_OFFSET) as bigint;
+
+const isParamWritable = (flags: number): boolean => (flags & PARAM_WRITABLE) !== 0;
+const isParamConstructOnly = (flags: number): boolean => (flags & PARAM_CONSTRUCT_ONLY) !== 0;
+const isParamLaxlyValidated = (flags: number): boolean => (flags & PARAM_LAX_VALIDATION) !== 0;
+
+const wasParamValueModified = (pspec: ExternalObject<Handle>, value: ExternalObject<Handle>): boolean =>
+    paramValueValidate(pspec, value) as boolean;
+
+function isBooleanValue(value: unknown): boolean {
+    return typeof value === "boolean";
+}
+
+function isStringValue(value: unknown): boolean {
+    return value == null || typeof value === "string";
+}
+
+function isStrvValue(value: unknown): boolean {
+    return value == null || (Array.isArray(value) && value.every((item) => typeof item === "string"));
+}
+
+function isNumberValue(value: unknown): boolean {
+    return typeof value === "number";
+}
+
+function isAnyValue(): boolean {
+    return true;
+}
+
+function isNullValue(value: unknown): boolean {
+    return value == null;
+}
+
+function integerGuardFor(minimum: number, maximum: number): ValueGuard {
+    return (value) => Number.isSafeInteger(value) && (value as number) >= minimum && (value as number) <= maximum;
+}
+
+function toWideInteger(value: unknown): bigint | undefined {
+    if (typeof value === "bigint") {
+        return value;
+    }
+
+    return Number.isSafeInteger(value) ? BigInt(value as number) : undefined;
+}
+
+function wideIntegerGuardFor(minimum: bigint, maximum: bigint): ValueGuard {
+    return (value) => {
+        const wide = toWideInteger(value);
+
+        return wide !== undefined && wide >= minimum && wide <= maximum;
+    };
+}
+
+function resolveGtype(value: unknown): bigint {
+    const instanceType = getInstanceType(value as object);
+
+    if (instanceType !== TYPE_INVALID) {
+        return instanceType;
+    }
+
+    return isTypedClass(value) ? value.__type__ : TYPE_INVALID;
+}
+
+function wrappedGuardFor(valueType: bigint): ValueGuard {
+    return (value) => value == null || typeIsA(resolveGtype(value), valueType);
+}
+
+function exactGuardFor(valueType: bigint): ValueGuard | undefined {
+    if (valueType === TYPE_GTYPE) {
+        return isWideUnsignedValue;
+    }
+
+    return valueType === getStrvType() ? isStrvValue : undefined;
+}
+
+function valueGuardFor(valueType: bigint): ValueGuard {
+    assertParamLayout();
+    const exact = exactGuardFor(valueType);
+
+    if (exact !== undefined) {
+        return exact;
+    }
+
+    const fundamental = typeFundamental(valueType);
+
+    if (WRAPPED_FUNDAMENTALS.has(fundamental)) {
+        return wrappedGuardFor(valueType);
+    }
+
+    return SCALAR_GUARDS.get(fundamental) ?? isAnyValue;
+}
+
+function readProbeLayout(flags: number): ParamLayout {
+    const probe = newParamSpecBoolean(LAYOUT_PROBE_NAME, null, null, false, flags) as ExternalObject<Handle>;
+    paramSpecRefSink(probe);
+
+    try {
+        return { flags: getParamFlags(probe), valueType: getParamValueType(probe) };
+    } finally {
+        paramSpecUnref(probe);
+    }
+}
+
+function isLayoutIntact(flags: number): boolean {
+    const layout = readProbeLayout(flags);
+
+    return (layout.flags & READ_FLAGS) === flags && layout.valueType === TYPE_BOOLEAN;
+}
+
+function assertParamLayout(): void {
+    if (layout.wasChecked) {
+        return;
+    }
+
+    layout.wasChecked = true;
+    const readWrite = PARAM_READABLE | PARAM_WRITABLE;
+
+    if (isLayoutIntact(readWrite) && isLayoutIntact(readWrite | PARAM_CONSTRUCT_ONLY | PARAM_LAX_VALIDATION)) {
+        return;
+    }
+
+    throw new Error(
+        "GParamSpec does not match the memory layout this build reads a property's flags and value type at",
+    );
+}
+
+export {
+    getParamFlags,
+    getParamValueType,
+    isParamConstructOnly,
+    isParamLaxlyValidated,
+    isParamWritable,
+    type ValueGuard,
+    valueGuardFor,
+    wasParamValueModified,
+};

package/src/promisify.ts

@@ -1,4 +1,4 @@
-import { tryGetHandle } from "./registry.js";
+import { getHandle } from "./registry.js";
 
 /**
  * Extracts the value of a completed asynchronous operation from its `GAsyncResult`, throwing when
@@ -57,7 +57,9 @@ const promisify = <R extends object, T>(
         const creationStack =
             process.env.NODE_ENV === "production" ? undefined : new Error("GTKX async operation started here");
 
-        asyncFn(...leading, tryGetHandle(cancellable), (_source: object | null, asyncResult: object) => {
+        const cancellableHandle = cancellable == null ? null : getHandle(cancellable);
+
+        asyncFn(...leading, cancellableHandle, (_source: object | null, asyncResult: object) => {
             settle({ finish, creationStack, resolve, reject }, asyncResult);
         });
     });