@gtkx/runtime 2.0.0-beta.1 → 2.0.0-beta.10

package/src/listeners.ts

@@ -1,22 +1,18 @@
-import { isSignalHandlerConnected, type SignalHandler, untrackConnection } from "./signal.js";
-
-/**
- * The connect and disconnect surface {@link onSignal}, {@link onceSignal} and {@link offSignal}
- * drive on an emitter.
- */
-type SignalConnectable = {
-    /** Connects a handler to a signal and returns its handler id. */
-    connect(signal: string, handler: SignalHandler, isAfter?: boolean): number;
-    /** Disconnects the handler previously connected under the given id. */
-    disconnect(handlerId: number): void;
-};
+import {
+    canonicalDetailedSignalName,
+    connectSignalByName,
+    disconnectSignal,
+    isSignalHandlerConnected,
+    type SignalHandler,
+} from "./signal.js";
 
 const listenerTable: WeakMap<object, Map<string, Map<SignalHandler, number[]>>> = new WeakMap();
 
 const findListenerHandlerId = (instance: object, signal: string, handler: SignalHandler): number | undefined =>
-    listenerTable.get(instance)?.get(signal)?.get(handler)?.at(-1);
+    listenerTable.get(instance)?.get(canonicalDetailedSignalName(signal))?.get(handler)?.at(-1);
 
 const trackListener = (instance: object, signal: string, handler: SignalHandler, handlerId: number): void => {
+    const key = canonicalDetailedSignalName(signal);
     let bySignal = listenerTable.get(instance);
 
     if (!bySignal) {
@@ -24,11 +20,11 @@ const trackListener = (instance: object, signal: string, handler: SignalHandler,
         listenerTable.set(instance, bySignal);
     }
 
-    let byHandler = bySignal.get(signal);
+    let byHandler = bySignal.get(key);
 
     if (!byHandler) {
         byHandler = new Map();
-        bySignal.set(signal, byHandler);
+        bySignal.set(key, byHandler);
     }
 
     let handlerIds = byHandler.get(handler);
@@ -52,8 +48,9 @@ const removeTrackedHandlerId = (handlerIds: number[], handlerId: number): number
 };
 
 const untrackHandlerId = (instance: object, signal: string, handlerId: number): void => {
+    const key = canonicalDetailedSignalName(signal);
     const bySignal = listenerTable.get(instance);
-    const byHandler = bySignal?.get(signal);
+    const byHandler = bySignal?.get(key);
 
     if (byHandler === undefined) {
         return;
@@ -66,7 +63,7 @@ const untrackHandlerId = (instance: object, signal: string, handlerId: number):
     }
 
     if (byHandler.size === 0) {
-        bySignal?.delete(signal);
+        bySignal?.delete(key);
     }
 };
 
@@ -79,8 +76,8 @@ const untrackHandlerId = (instance: object, signal: string, handlerId: number):
  * @param handler The callback invoked on each emission.
  * @param isAfter When true, run the handler after the default handler.
  */
-function onSignal(instance: SignalConnectable, signal: string, handler: SignalHandler, isAfter?: boolean): void {
-    const handlerId = instance.connect(signal, handler, isAfter);
+function onSignal(instance: object, signal: string, handler: SignalHandler, isAfter?: boolean): void {
+    const handlerId = connectSignalByName(instance, signal, handler, isAfter);
     trackListener(instance, signal, handler, handlerId);
 }
 
@@ -93,18 +90,17 @@ function onSignal(instance: SignalConnectable, signal: string, handler: SignalHa
  * @param handler The callback invoked on the first emission.
  * @param isAfter When true, run the handler after the default handler.
  */
-function onceSignal(instance: SignalConnectable, signal: string, handler: SignalHandler, isAfter?: boolean): void {
+function onceSignal(instance: object, signal: string, handler: SignalHandler, isAfter?: boolean): void {
     let handlerId = 0;
 
     const wrapped: SignalHandler = (...args) => {
         untrackHandlerId(instance, signal, handlerId);
-        untrackConnection(instance, handlerId);
-        instance.disconnect(handlerId);
+        disconnectSignal(instance, handlerId);
 
         return handler(...args);
     };
 
-    handlerId = instance.connect(signal, wrapped, isAfter);
+    handlerId = connectSignalByName(instance, signal, wrapped, isAfter);
     trackListener(instance, signal, wrapped, handlerId);
     trackListener(instance, signal, handler, handlerId);
 }
@@ -117,7 +113,7 @@ function onceSignal(instance: SignalConnectable, signal: string, handler: Signal
  * @param signal The signal name the handler was connected to.
  * @param handler The handler to disconnect.
  */
-function offSignal(instance: SignalConnectable, signal: string, handler: SignalHandler): void {
+function offSignal(instance: object, signal: string, handler: SignalHandler): void {
     const handlerId = findListenerHandlerId(instance, signal, handler);
 
     if (handlerId === undefined) {
@@ -125,13 +121,12 @@ function offSignal(instance: SignalConnectable, signal: string, handler: SignalH
     }
 
     untrackHandlerId(instance, signal, handlerId);
-    untrackConnection(instance, handlerId);
 
     if (!isSignalHandlerConnected(instance, handlerId)) {
         return;
     }
 
-    instance.disconnect(handlerId);
+    disconnectSignal(instance, handlerId);
 }
 
 export { onSignal, onceSignal, offSignal };

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/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 { fromObjectPropertyValue, 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 getProperty<
+    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 getProperty(obj: object, propertyName: string, descriptor: Descriptor): unknown;
+function getProperty(obj: object, propertyName: string, descriptor?: Descriptor): unknown {
+    if (arguments.length === 2) {
+        const property = readableObjectPropertyFor(obj, propertyName);
+        gObjectGetProperty(getHandle(obj), property.name, property.value);
+
+        return fromObjectPropertyValue(property.value);
+    }
+
+    if (descriptor === undefined) {
+        throw new TypeError("getProperty requires a property descriptor when called with three arguments");
+    }
+
     const value = newValueForDescriptor(descriptor);
     gObjectGetProperty(getHandle(obj), propertyName, value);
 
@@ -192,15 +220,37 @@ 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 setProperty<
+    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 setProperty(obj: object, propertyName: string, descriptor: Descriptor, jsValue: unknown): void;
+function setProperty(
+    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 {
     newObjectWithProperties,
-    getObjectProperty,
+    getProperty,
     registerConstructProperties,
-    setObjectProperty,
+    setProperty,
     type ConstructBinding,
     type ConstructBindings,
 };

package/src/properties.ts

@@ -55,7 +55,7 @@ type AccessorBase = PropertyCheck & {
 type DeclaredAccessor = AccessorBase & {
     isInterfaceProperty?: false;
     memberName: string;
-    hasGeneratedMember: boolean;
+    hasMemberAccessor: boolean;
 };
 
 type InterfaceAccessor = AccessorBase & { isInterfaceProperty: true };
@@ -100,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(
@@ -214,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") {
@@ -283,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));
@@ -333,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 {
@@ -345,10 +366,35 @@ function lookupCoercionCheck(gtype: bigint, name: string): PropertyCheck | null
     }
 }
 
-function coercionCheckFor(gtype: bigint, name: string): PropertyCheck | null {
-    const checks = coercionChecks.getOrInsertComputed(gtype, () => new Map<string, PropertyCheck | null>());
+function propertyCheckFor(gtype: bigint, name: string): PropertyCheck | null {
+    const checks = propertyChecks.getOrInsertComputed(gtype, () => new Map<string, PropertyCheck | null>());
+
+    return checks.getOrInsertComputed(name, () => lookupPropertyCheck(gtype, name));
+}
+
+function objectPropertyCheckFor(instance: object, name: string): PropertyCheck {
+    const gtype = getInstanceType(instance);
+    const check = typeIsA(gtype, TYPE_OBJECT) ? propertyCheckFor(gtype, name) : null;
+
+    if (check === null) {
+        throw new TypeError(`${instanceClassName(instance)} has no GObject property named '${name}'`);
+    }
 
-    return checks.getOrInsertComputed(name, () => lookupCoercionCheck(gtype, 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 {
@@ -384,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);
 }
@@ -499,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;
     }
 
@@ -513,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)) {
@@ -586,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;
     }
 
@@ -686,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);
@@ -770,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 };