@gtkx/runtime 1.6.0 → 2.0.0-beta.2

package/src/mixin.ts

@@ -17,6 +17,12 @@ type MixinReceiver = {
  */
 type Mixin = (base: AnyClass<MixinReceiver>) => AnyClass;
 
+const syntheticSignalMembers: WeakMap<object, ReadonlySet<string>> = new WeakMap();
+
+function markSyntheticSignalMembers(klass: AnyClass, names: readonly string[]): void {
+    syntheticSignalMembers.set(klass.prototype, new Set(names));
+}
+
 function isDefinedInClassChain(prototype: object, key: string): boolean {
     let current: object | null = prototype;
 
@@ -31,12 +37,28 @@ function isDefinedInClassChain(prototype: object, key: string): boolean {
     return false;
 }
 
-function copyLayerMember(target: AnyClass, layer: object, key: string): void {
+function isNaturalInClassChain(prototype: object, key: string): boolean {
+    let current: object | null = prototype;
+
+    while (current !== null && current !== Object.prototype) {
+        if (Object.hasOwn(current, key)) {
+            return syntheticSignalMembers.get(current)?.has(key) !== true;
+        }
+
+        current = Reflect.getPrototypeOf(current);
+    }
+
+    return false;
+}
+
+function copyLayerMember(target: AnyClass, layer: object, key: string, inheritedOverrides: Set<string>): void {
     if (key === "constructor") {
         return;
     }
 
-    if (isDefinedInClassChain(target.prototype, key)) {
+    const isProtectedInherited = !inheritedOverrides.has(key) && isDefinedInClassChain(target.prototype, key);
+
+    if (isProtectedInherited || Object.hasOwn(target.prototype, key)) {
         return;
     }
 
@@ -47,9 +69,9 @@ function copyLayerMember(target: AnyClass, layer: object, key: string): void {
     }
 }
 
-function copyLayerMembers(target: AnyClass, layer: object): void {
+function copyLayerMembers(target: AnyClass, layer: object, inheritedOverrides: Set<string> = new Set()): void {
     for (const key of Object.getOwnPropertyNames(layer)) {
-        copyLayerMember(target, layer, key);
+        copyLayerMember(target, layer, key, inheritedOverrides);
     }
 }
 
@@ -60,7 +82,8 @@ function copyLayerMembers(target: AnyClass, layer: object): void {
  * @param target The class whose prototype receives the mixin members.
  * @param mixins The mixins to apply, in order.
  */
-function installMixins(target: AnyClass, mixins: Mixin[]): void {
+function installMixins(target: AnyClass, mixins: Mixin[], inheritedOverrideNames: Iterable<string> = []): void {
+    const inheritedOverrides = new Set(inheritedOverrideNames);
     const empty: AnyClass<MixinReceiver> = class {
         connect(): number {
             return 0;
@@ -72,7 +95,7 @@ function installMixins(target: AnyClass, mixins: Mixin[]): void {
     };
 
     for (const mixin of mixins) {
-        copyLayerMembers(target, mixin(empty).prototype);
+        copyLayerMembers(target, mixin(empty).prototype, inheritedOverrides);
     }
 }
 
@@ -82,11 +105,34 @@ function dropLayerMembers(layer: AnyClass, names: Set<string>): void {
     }
 }
 
+function createMixinLayer(parent: AnyClass<MixinReceiver>, mixin: Mixin, inheritedNames: Set<string>): AnyClass {
+    const layer = mixin(parent);
+    const protectedNames = new Set(inheritedNames);
+
+    for (const key of Object.getOwnPropertyNames(layer.prototype)) {
+        if (key !== "constructor" && isNaturalInClassChain(parent.prototype, key)) {
+            protectedNames.add(key);
+        }
+    }
+
+    dropLayerMembers(layer, protectedNames);
+
+    return layer;
+}
+
 function insertMixinLayer(target: AnyClass, mixin: Mixin, inheritedNames: Set<string>): void {
-    const layer = mixin(getParentClass(target) as AnyClass<MixinReceiver>);
-    dropLayerMembers(layer, inheritedNames);
+    const parent = getParentClass(target) as AnyClass<MixinReceiver>;
+    const layer = createMixinLayer(parent, mixin, inheritedNames);
     Object.setPrototypeOf(target.prototype, layer.prototype);
     Object.setPrototypeOf(target, layer);
 }
 
-export { copyLayerMembers, insertMixinLayer, installMixins, type MixinReceiver, type Mixin };
+export {
+    copyLayerMembers,
+    createMixinLayer,
+    insertMixinLayer,
+    installMixins,
+    markSyntheticSignalMembers,
+    type MixinReceiver,
+    type Mixin,
+};

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/object.ts

@@ -3,9 +3,16 @@ import { type AnyClass, getParentClass } from "@gtkx/utils";
 import { bind } from "./bind.js";
 import { objectT, stringT, voidT } from "./descriptors.js";
 import { LIB, VALUE_T } from "./library.js";
-import { coercePropertyValue, type ConstructProperty, constructPropertyFor } from "./properties.js";
+import {
+    coercePropertyValue,
+    type ConstructProperty,
+    constructPropertyFor,
+    readableObjectPropertyFor,
+    writableObjectPropertyFor,
+} from "./properties.js";
+import { propertyMapOverride, writablePropertyMapOverride } from "./property-brand.js";
 import { getHandle, registerWrapper } from "./registry.js";
-import { fromValueForDescriptor, newValueForDescriptor, toValue } from "./value.js";
+import { fromValue, fromValueForDescriptor, newValueForDescriptor, toValue } from "./value.js";
 
 /**
  * One construct property a wrapper class accepts: the canonical `GObject` name it is set under,
@@ -172,7 +179,28 @@ function newObjectWithProperties<T extends object>(gtype: bigint, props: object,
  * @param propertyName The property name.
  * @param descriptor Describes the property's type.
  */
-function getObjectProperty(obj: object, propertyName: string, descriptor: Descriptor): unknown {
+function getObjectProperty<
+    TObject extends { __properties__: object },
+    TPropertyMap extends object = TObject extends { [propertyMapOverride]?: infer TResolver }
+        ? TResolver extends () => infer TMap
+            ? Extract<NonNullable<TMap>, object>
+            : TObject["__properties__"]
+        : TObject["__properties__"],
+    TName extends Extract<keyof NoInfer<TPropertyMap>, string> = Extract<keyof NoInfer<TPropertyMap>, string>,
+>(obj: TObject, propertyName: TName): NoInfer<TPropertyMap>[TName];
+function getObjectProperty(obj: object, propertyName: string, descriptor: Descriptor): unknown;
+function getObjectProperty(obj: object, propertyName: string, descriptor?: Descriptor): unknown {
+    if (arguments.length === 2) {
+        const property = readableObjectPropertyFor(obj, propertyName);
+        gObjectGetProperty(getHandle(obj), property.name, property.value);
+
+        return fromValue(property.value);
+    }
+
+    if (descriptor === undefined) {
+        throw new TypeError("getObjectProperty requires a property descriptor when called with three arguments");
+    }
+
     const value = newValueForDescriptor(descriptor);
     gObjectGetProperty(getHandle(obj), propertyName, value);
 
@@ -192,8 +220,30 @@ function getObjectProperty(obj: object, propertyName: string, descriptor: Descri
  * @param descriptor Describes the property's type.
  * @param jsValue The value to set.
  */
-function setObjectProperty(obj: object, propertyName: string, descriptor: Descriptor, jsValue: unknown): void {
-    gObjectSetProperty(getHandle(obj), propertyName, toValue(descriptor, jsValue));
+function setObjectProperty<
+    TObject extends { __writableProperties__: object },
+    TPropertyMap extends object = TObject extends { [writablePropertyMapOverride]?: infer TResolver }
+        ? TResolver extends () => infer TMap
+            ? Extract<NonNullable<TMap>, object>
+            : TObject["__writableProperties__"]
+        : TObject["__writableProperties__"],
+    TName extends Extract<keyof NoInfer<TPropertyMap>, string> = Extract<keyof NoInfer<TPropertyMap>, string>,
+>(obj: TObject, propertyName: TName, jsValue: NoInfer<TPropertyMap>[TName]): void;
+function setObjectProperty(obj: object, propertyName: string, descriptor: Descriptor, jsValue: unknown): void;
+function setObjectProperty(
+    obj: object,
+    propertyName: string,
+    descriptorOrValue: unknown,
+    jsValue?: unknown,
+): void {
+    if (arguments.length === 3) {
+        const property = writableObjectPropertyFor(obj, propertyName, descriptorOrValue);
+        gObjectSetProperty(getHandle(obj), property.name, property.value);
+
+        return;
+    }
+
+    gObjectSetProperty(getHandle(obj), propertyName, toValue(descriptorOrValue as Descriptor, jsValue));
 }
 
 export {

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";
@@ -56,7 +55,7 @@ type AccessorBase = PropertyCheck & {
 type DeclaredAccessor = AccessorBase & {
     isInterfaceProperty?: false;
     memberName: string;
-    hasGeneratedMember: boolean;
+    hasMemberAccessor: boolean;
 };
 
 type InterfaceAccessor = AccessorBase & { isInterfaceProperty: true };
@@ -101,7 +100,7 @@ const paramSpecDefaultValue = bind(LIB, "g_param_spec_get_default_value", [PARAM
 const paramSpecName = bind(LIB, "g_param_spec_get_name", [PARAM_T], stringT("borrowed"));
 const typeClassRef = bind(LIB, "g_type_class_ref", [biguint64T], CLASS_T);
 const typeClassUnref = bind(LIB, "g_type_class_unref", [CLASS_T], voidT);
-const coercionChecks: Map<bigint, Map<string, PropertyCheck | null>> = new Map();
+const propertyChecks: Map<bigint, Map<string, PropertyCheck | null>> = new Map();
 const classFindProperty = bind(LIB, "g_object_class_find_property", [CLASS_T, stringT("borrowed")], PARAM_T);
 
 const classListProperties = bind(
@@ -215,8 +214,11 @@ const findSourceSpec = (source: bigint | AnyClass, name: string): ExternalObject
  * @param source The GType, wrapper class or interface declaring the property.
  * @returns Handle of the override spec.
  */
-const newParamSpecOverride = (name: string, source: bigint | AnyClass): ExternalObject<Handle> =>
-    paramSpecOverrideNew(name, findSourceSpec(source, name)) as ExternalObject<Handle>;
+const newParamSpecOverride = (name: string, source: bigint | AnyClass): ExternalObject<Handle> => {
+    const canonicalName = canonicalCase(name);
+
+    return paramSpecOverrideNew(canonicalName, findSourceSpec(source, canonicalName)) as ExternalObject<Handle>;
+};
 
 function describeValue(value: unknown): string {
     if (typeof value === "string") {
@@ -284,6 +286,24 @@ function assertWritable(instance: object, check: PropertyCheck, value: unknown):
     throw new TypeError(propertyMessage(instance, check, refusalTail(check, value, READ_ONLY_REASON)));
 }
 
+function assertReadable(instance: object, check: PropertyCheck): void {
+    if (isParamReadable(check.flags)) {
+        return;
+    }
+
+    throw new TypeError(
+        propertyMessage(instance, check, `cannot read property '${check.propertyName}'; the property is write-only`),
+    );
+}
+
+function assertMutable(instance: object, check: PropertyCheck, value: unknown): void {
+    assertWritable(instance, check, value);
+
+    if (isParamConstructOnly(check.flags)) {
+        throw new TypeError(propertyMessage(instance, check, refusalTail(check, value, CONSTRUCT_ONLY_REASON)));
+    }
+}
+
 function writeHeld(check: PropertyCheck, gValue: ExternalObject<Handle>, value: unknown): void {
     check.write ??= valueWriterFor(check.valueType);
     check.write(gValue, check.narrowValue(value));
@@ -334,7 +354,7 @@ function isReadableProperty(gtype: bigint, propertyName: string): boolean {
     }
 }
 
-function lookupCoercionCheck(gtype: bigint, name: string): PropertyCheck | null {
+function lookupPropertyCheck(gtype: bigint, name: string): PropertyCheck | null {
     const klass = typeClassRef(gtype) as ExternalObject<Handle>;
 
     try {
@@ -346,24 +366,37 @@ function lookupCoercionCheck(gtype: bigint, name: string): PropertyCheck | null
     }
 }
 
-function coercionCheckFor(gtype: bigint, name: string): PropertyCheck | null {
-    let checks = coercionChecks.get(gtype);
+function propertyCheckFor(gtype: bigint, name: string): PropertyCheck | null {
+    const checks = propertyChecks.getOrInsertComputed(gtype, () => new Map<string, PropertyCheck | null>());
 
-    if (checks === undefined) {
-        checks = new Map();
-        coercionChecks.set(gtype, checks);
-    }
+    return checks.getOrInsertComputed(name, () => lookupPropertyCheck(gtype, name));
+}
 
-    let check = checks.get(name);
+function objectPropertyCheckFor(instance: object, name: string): PropertyCheck {
+    const gtype = getInstanceType(instance);
+    const check = typeIsA(gtype, TYPE_OBJECT) ? propertyCheckFor(gtype, name) : null;
 
-    if (check === undefined) {
-        check = lookupCoercionCheck(gtype, name);
-        checks.set(name, check);
+    if (check === null) {
+        throw new TypeError(`${instanceClassName(instance)} has no GObject property named '${name}'`);
     }
 
     return check;
 }
 
+function readableObjectPropertyFor(instance: object, name: string): ConstructProperty {
+    const check = objectPropertyCheckFor(instance, name);
+    assertReadable(instance, check);
+
+    return { name: check.propertyName, value: newValueForType(check.valueType) };
+}
+
+function writableObjectPropertyFor(instance: object, name: string, value: unknown): ConstructProperty {
+    const check = objectPropertyCheckFor(instance, name);
+    assertMutable(instance, check, value);
+
+    return { name: check.propertyName, value: checkedValueFor(instance, check, value) };
+}
+
 function truncateToWhole(check: PropertyCheck, value: number): number {
     const range = WHOLE_NUMBER_RANGES.get(typeFundamental(check.valueType));
 
@@ -397,7 +430,7 @@ function coercePropertyValue(gtype: bigint, propertyName: string, value: unknown
         return value;
     }
 
-    const check = coercionCheckFor(gtype, propertyName);
+    const check = propertyCheckFor(gtype, propertyName);
 
     return check === null ? value : coerceNumber(check, value);
 }
@@ -512,12 +545,35 @@ function checkedSetter(accessor: DeclaredAccessor): (this: object, value: unknow
     };
 }
 
-function hasOwnMember(prototype: object, alias: string): boolean {
-    return Object.getOwnPropertyDescriptor(prototype, alias) !== undefined;
+function memberDescriptorFor(prototype: object, name: string): PropertyDescriptor | undefined {
+    let current: object | null = prototype;
+
+    while (current !== null) {
+        const descriptor = Object.getOwnPropertyDescriptor(current, name);
+
+        if (descriptor !== undefined) {
+            return descriptor;
+        }
+
+        current = Reflect.getPrototypeOf(current);
+    }
+
+    return undefined;
+}
+
+function isMemberAccessor(descriptor: PropertyDescriptor | undefined): boolean {
+    return descriptor !== undefined && ("get" in descriptor || "set" in descriptor);
 }
 
 function defineAccessor(prototype: object, descriptor: PropertyDescriptor, alias: string): void {
-    if (hasOwnMember(prototype, alias)) {
+    if (Object.getOwnPropertyDescriptor(prototype, alias) !== undefined) {
+        return;
+    }
+
+    const parent = Reflect.getPrototypeOf(prototype);
+    const inherited = parent === null ? undefined : memberDescriptorFor(parent, alias);
+
+    if (inherited !== undefined && !isMemberAccessor(inherited)) {
         return;
     }
 
@@ -526,13 +582,13 @@ function defineAccessor(prototype: object, descriptor: PropertyDescriptor, alias
 
 function installAccessors(klass: AnyClass, accessor: DeclaredAccessor): void {
     const prototype = (klass as { prototype: object }).prototype;
-    accessor.hasGeneratedMember = !hasOwnMember(prototype, accessor.memberName);
+    accessor.hasMemberAccessor = isMemberAccessor(Object.getOwnPropertyDescriptor(prototype, accessor.memberName));
 
     const descriptor: PropertyDescriptor = {
         configurable: true,
         enumerable: true,
-        get: accessor.hasGeneratedMember ? storedGetter(accessor) : memberGetter(accessor),
-        set: accessor.hasGeneratedMember ? checkedSetter(accessor) : memberSetter(accessor),
+        get: accessor.hasMemberAccessor ? memberGetter(accessor) : storedGetter(accessor),
+        set: accessor.hasMemberAccessor ? memberSetter(accessor) : checkedSetter(accessor),
     };
 
     for (const alias of accessorNames(accessor.name)) {
@@ -599,7 +655,13 @@ function callMember(instance: object, member: string, args: unknown[]): unknown
 }
 
 function backingMemberFor(instance: object, accessor: DeclaredAccessor): string | undefined {
-    if (accessor.hasGeneratedMember && !Object.hasOwn(instance, accessor.memberName)) {
+    if (accessor.hasMemberAccessor) {
+        return accessor.memberName;
+    }
+
+    const descriptor = Object.getOwnPropertyDescriptor(instance, accessor.memberName);
+
+    if (descriptor === undefined || ("value" in descriptor && typeof descriptor.value === "function")) {
         return undefined;
     }
 
@@ -699,7 +761,7 @@ function buildAccessor(klass: AnyClass, name: string, pspec: PropertySpec): Decl
         ...checkFor(getHandle(pspec), name),
         memberName: camelCase(name),
         storage: Symbol(`gtkx:property:${name}`),
-        hasGeneratedMember: false,
+        hasMemberAccessor: false,
     };
 
     installAccessors(klass, accessor);
@@ -783,8 +845,10 @@ export {
     makeGetProperty,
     makeSetProperty,
     newParamSpecOverride,
+    readableObjectPropertyFor,
     SET_PROPERTY_VFUNC,
     toNativeProperties,
+    writableObjectPropertyFor,
     type ConstructProperty,
     type PropertyDispatch,
     type PropertySpec,

package/src/property-brand.ts

@@ -0,0 +1,5 @@
+const propertyMapOverride: unique symbol = Symbol("gtkx.propertyMapOverride");
+const writablePropertyMapOverride: unique symbol = Symbol("gtkx.writablePropertyMapOverride");
+const descriptorFreePropertySpec: unique symbol = Symbol("gtkx.descriptorFreePropertySpec");
+
+export { descriptorFreePropertySpec, propertyMapOverride, writablePropertyMapOverride };