@gtkx/runtime 1.2.2 → 1.4.0

package/src/properties.ts

@@ -1,24 +1,35 @@
 import type { ExternalObject, Handle, RegisterClassProperty } from "@gtkx/native";
 import type { AnyClass } from "@gtkx/utils";
-import { camelCase, kebabCase } from "@gtkx/utils";
+import { camelCase, kebabCase, toCamelIdentifier } from "@gtkx/utils";
 import { bind } from "./bind.js";
-import { biguint64T, stringT, structT, voidT } from "./descriptors.js";
+import { biguint64T, fundamentalT, refT, sizedArrayT, stringT, structT, uint32T, voidT } from "./descriptors.js";
 import { LIB, PARAM_T, VALUE_T } from "./library.js";
 import {
     getParamFlags,
     getParamValueType,
     isParamConstructOnly,
+    isParamExplicitlyNotified,
     isParamLaxlyValidated,
+    isParamReadable,
     isParamWritable,
     type ValueGuard,
     valueGuardFor,
     wasParamValueModified,
+    WHOLE_NUMBER_RANGES,
 } from "./param-spec.js";
-import { getHandle, getInterfaceProperties, instanceClassName, type InterfaceProperty } from "./registry.js";
-import { typeName } from "./type.js";
+import {
+    getClassType,
+    getHandle,
+    getInstanceType,
+    getInterfaceProperties,
+    instanceClassName,
+    type InterfaceProperty,
+} from "./registry.js";
+import { TYPE_INTERFACE, TYPE_INVALID, TYPE_OBJECT, typeFundamental, typeIsA, typeName } from "./type.js";
 import {
     fromValue,
     newValueForType,
+    valueGuardOverrideFor,
     type ValueNarrower,
     valueNarrowerFor,
     type ValueWriter,
@@ -37,14 +48,19 @@ type PropertyCheck = {
     scratch?: ExternalObject<Handle>;
 };
 
-type PropertyAccessor = PropertyCheck & {
-    memberName: string;
+type AccessorBase = PropertyCheck & {
     storage: symbol;
-    hasGeneratedMember: boolean;
-    isInterfaceProperty?: boolean;
     delegate?: InterfaceProperty;
 };
 
+type DeclaredAccessor = AccessorBase & {
+    isInterfaceProperty?: false;
+    memberName: string;
+    hasGeneratedMember: boolean;
+};
+
+type InterfaceAccessor = AccessorBase & { isInterfaceProperty: true };
+type PropertyAccessor = DeclaredAccessor | InterfaceAccessor;
 /** A `GObject.ParamSpec` wrapper describing one property's name, type, flags and default. */
 type PropertySpec = object;
 
@@ -72,13 +88,34 @@ const SET_PROPERTY_VFUNC = "vfuncSetProperty";
 const READ_ONLY_REASON = "the property is read-only";
 const CONSTRUCT_ONLY_REASON = "the property can only be set when the object is constructed";
 const CLASS_T = structT("borrowed");
+const CANONICAL_NAME_PATTERN = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+const DECLARED_NAMES = Symbol("gtkx:declaredPropertyNames");
+
+const OVERRIDE_PARAM_T = fundamentalT(LIB, "g_param_spec_ref_sink", "g_param_spec_unref", {
+    ownership: "borrowed",
+    typeName: "GParam",
+});
+
 const interfaceStorages: Map<string, symbol> = new Map();
 const paramSpecDefaultValue = bind(LIB, "g_param_spec_get_default_value", [PARAM_T], VALUE_T);
 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 classFindProperty = bind(LIB, "g_object_class_find_property", [CLASS_T, stringT("borrowed")], PARAM_T);
 
+const classListProperties = bind(
+    LIB,
+    "g_object_class_list_properties",
+    [CLASS_T, refT(uint32T)],
+    sizedArrayT(PARAM_T, 1, "full"),
+);
+
+const defaultInterfaceRef = bind(LIB, "g_type_default_interface_ref", [biguint64T], CLASS_T);
+const defaultInterfaceUnref = bind(LIB, "g_type_default_interface_unref", [CLASS_T], voidT);
+const interfaceFindProperty = bind(LIB, "g_object_interface_find_property", [CLASS_T, stringT("borrowed")], PARAM_T);
+const paramSpecOverrideNew = bind(LIB, "g_param_spec_override", [stringT("borrowed"), PARAM_T], OVERRIDE_PARAM_T);
+
 const getPropertyName = (pspec: PropertySpec): string => paramSpecName(getHandle(pspec)) as string;
 const underscoreCase = (name: string): string => name.replaceAll("-", "_");
 const canonicalCase = (name: string): string => kebabCase(name).replaceAll("_", "-");
@@ -102,17 +139,85 @@ function checkFor(handle: ExternalObject<Handle>, name: string): PropertyCheck {
         handle,
         flags: getParamFlags(handle),
         valueType,
-        canHoldValue: valueGuardFor(valueType),
+        canHoldValue: valueGuardOverrideFor(valueType) ?? valueGuardFor(valueType),
         narrowValue: valueNarrowerFor(valueType),
     };
 }
 
+function accessorSpecs(klass: ExternalObject<Handle>): Map<string, ExternalObject<Handle>> {
+    const specs: Map<string, ExternalObject<Handle>> = new Map();
+    const countRef = { value: 0 };
+
+    for (const pspec of classListProperties(klass, countRef) as ExternalObject<Handle>[]) {
+        specs.set(toCamelIdentifier(paramSpecName(pspec) as string), pspec);
+    }
+
+    return specs;
+}
+
 function findPropertySpec(klass: ExternalObject<Handle>, name: string): ExternalObject<Handle> | null {
-    const found = classFindProperty(klass, name) as ExternalObject<Handle> | null;
+    const found = (classFindProperty(klass, name) ??
+        classFindProperty(klass, canonicalCase(name))) as ExternalObject<Handle> | null;
 
-    return found ?? (classFindProperty(klass, canonicalCase(name)) as ExternalObject<Handle> | null);
+    return found ?? accessorSpecs(klass).get(toCamelIdentifier(name)) ?? null;
 }
 
+const sourceLabel = (source: bigint | AnyClass, gtype: bigint): string =>
+    typeName(gtype) ?? (typeof source === "function" ? source.name : String(source));
+
+const findInterfaceSpec = (gtype: bigint, name: string): ExternalObject<Handle> | null => {
+    const vtable = defaultInterfaceRef(gtype) as ExternalObject<Handle>;
+
+    try {
+        return interfaceFindProperty(vtable, name) as ExternalObject<Handle> | null;
+    } finally {
+        defaultInterfaceUnref(vtable);
+    }
+};
+
+const findClassSpec = (gtype: bigint, name: string): ExternalObject<Handle> | null => {
+    const klass = typeClassRef(gtype) as ExternalObject<Handle>;
+
+    try {
+        return classFindProperty(klass, name) as ExternalObject<Handle> | null;
+    } finally {
+        typeClassUnref(klass);
+    }
+};
+
+const findSourceSpec = (source: bigint | AnyClass, name: string): ExternalObject<Handle> => {
+    const gtype = typeof source === "bigint" ? source : getClassType(source);
+    const isInterface = typeIsA(gtype, TYPE_INTERFACE);
+
+    if (!isInterface && !typeIsA(gtype, TYPE_OBJECT)) {
+        throw new TypeError(
+            `paramSpecOverride: '${sourceLabel(source, gtype)}' is neither a registered object class nor an interface`,
+        );
+    }
+
+    const pspec = isInterface ? findInterfaceSpec(gtype, name) : findClassSpec(gtype, name);
+
+    if (pspec === null) {
+        throw new TypeError(`paramSpecOverride: type '${sourceLabel(source, gtype)}' has no property named '${name}'`);
+    }
+
+    return pspec;
+};
+
+/**
+ * Creates the handle of a `GParamSpec` that redirects to the property `source` declares under
+ * `name` — the equivalent of `g_param_spec_override`, which introspection does not expose.
+ *
+ * Throws when `source` is neither a GType nor a registered class or interface, and when it
+ * declares no property under `name`.
+ *
+ * @param name Canonical name of the property to override.
+ * @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>;
+
 function describeValue(value: unknown): string {
     if (typeof value === "string") {
         return JSON.stringify(value);
@@ -213,6 +318,113 @@ function constructValueFor(wrapper: object, check: PropertyCheck, value: unknown
     return { name: check.propertyName, value: checkedValueFor(wrapper, check, value) };
 }
 
+/**
+ * Whether the type declares a readable GObject property under `propertyName`, asking GObject itself
+ * rather than looking for a generated accessor, which codegen omits when a method shares the name.
+ */
+function isReadableProperty(gtype: bigint, propertyName: string): boolean {
+    const klass = typeClassRef(gtype) as ExternalObject<Handle>;
+
+    try {
+        const pspec = findPropertySpec(klass, propertyName);
+
+        return pspec !== null && isParamReadable(getParamFlags(pspec));
+    } finally {
+        typeClassUnref(klass);
+    }
+}
+
+function lookupCoercionCheck(gtype: bigint, name: string): PropertyCheck | null {
+    const klass = typeClassRef(gtype) as ExternalObject<Handle>;
+
+    try {
+        const pspec = findPropertySpec(klass, name);
+
+        return pspec === null ? null : checkFor(pspec, name);
+    } finally {
+        typeClassUnref(klass);
+    }
+}
+
+function coercionCheckFor(gtype: bigint, name: string): PropertyCheck | null {
+    let checks = coercionChecks.get(gtype);
+
+    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;
+}
+
+function truncateToWhole(check: PropertyCheck, value: number): number {
+    const range = WHOLE_NUMBER_RANGES.get(typeFundamental(check.valueType));
+
+    if (range === undefined) {
+        return value;
+    }
+
+    return Math.min(range[1], Math.max(range[0], Math.trunc(value)));
+}
+
+function validatedNumber(check: PropertyCheck, number: number): number {
+    check.scratch ??= newValueForType(check.valueType);
+
+    try {
+        writeHeld(check, check.scratch, number);
+    } catch {
+        return number;
+    }
+
+    return wasParamValueModified(check.handle, check.scratch) ? (fromValue(check.scratch) as number) : number;
+}
+
+function coerceNumber(check: PropertyCheck, value: number): number {
+    const number = truncateToWhole(check, value);
+
+    return check.canHoldValue(number) ? validatedNumber(check, number) : value;
+}
+
+function coercePropertyValue(gtype: bigint, propertyName: string, value: unknown): unknown {
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        return value;
+    }
+
+    const check = coercionCheckFor(gtype, propertyName);
+
+    return check === null ? value : coerceNumber(check, value);
+}
+
+/**
+ * Fits a number to what a GObject property accepts, the way an animation writing a value on every
+ * frame needs: a fractional number headed for a property that holds whole numbers, such as a
+ * `gint`, an enum, or flags, is truncated toward zero, and a number outside the range the
+ * property's `GObject.ParamSpec` allows is clamped to it, so the write that follows never trips
+ * GObject's range check. Anything that is not a finite number, a number the property cannot hold
+ * at all, and a name the object installs no property under come back unchanged.
+ *
+ * @param obj The object the value is about to be written to.
+ * @param propertyName The property name, dashed or camelCased.
+ * @param value The value about to be written.
+ * @returns The value as the property accepts it.
+ */
+function coerceObjectProperty(obj: object, propertyName: string, value: unknown): unknown {
+    if (typeof value !== "number") {
+        return value;
+    }
+
+    const gtype = getInstanceType(obj);
+
+    return gtype === TYPE_INVALID ? value : coercePropertyValue(gtype, propertyName, value);
+}
+
 function constructPropertyFor(
     gtype: bigint,
     name: string,
@@ -268,13 +480,13 @@ function storedGetter(accessor: PropertyAccessor): (this: object) => unknown {
     };
 }
 
-function memberGetter(accessor: PropertyAccessor): (this: object) => unknown {
+function memberGetter(accessor: DeclaredAccessor): (this: object) => unknown {
     return function get(this: object) {
         return (this as Record<string, unknown>)[accessor.memberName];
     };
 }
 
-function memberSetter(accessor: PropertyAccessor): (this: object, value: unknown) => void {
+function memberSetter(accessor: DeclaredAccessor): (this: object, value: unknown) => void {
     return function set(this: object, value: unknown) {
         (this as Record<string, unknown>)[accessor.memberName] = value;
     };
@@ -286,7 +498,7 @@ function refusalFor(accessor: PropertyAccessor, reason: string): (this: object,
     };
 }
 
-function checkedSetter(accessor: PropertyAccessor): (this: object, value: unknown) => void {
+function checkedSetter(accessor: DeclaredAccessor): (this: object, value: unknown) => void {
     if (!isParamWritable(accessor.flags)) {
         return refusalFor(accessor, READ_ONLY_REASON);
     }
@@ -312,7 +524,7 @@ function defineAccessor(prototype: object, descriptor: PropertyDescriptor, alias
     Object.defineProperty(prototype, alias, descriptor);
 }
 
-function installAccessors(klass: AnyClass, accessor: PropertyAccessor): void {
+function installAccessors(klass: AnyClass, accessor: DeclaredAccessor): void {
     const prototype = (klass as { prototype: object }).prototype;
     accessor.hasGeneratedMember = !hasOwnMember(prototype, accessor.memberName);
 
@@ -341,16 +553,14 @@ function storageFor(propertyName: string): symbol {
     return created;
 }
 
-function interfaceAccessorFor(dispatch: PropertyDispatch, pspec: PropertySpec): PropertyAccessor {
+function interfaceAccessorFor(dispatch: PropertyDispatch, pspec: PropertySpec): InterfaceAccessor {
     const handle = getHandle(pspec);
     const propertyName = paramSpecName(handle) as string;
     const delegate = dispatch.delegates.get(propertyName);
 
-    const accessor: PropertyAccessor = {
+    const accessor: InterfaceAccessor = {
         ...checkFor(handle, propertyName),
-        memberName: camelCase(propertyName),
         storage: storageFor(propertyName),
-        hasGeneratedMember: false,
         isInterfaceProperty: true,
     };
 
@@ -388,7 +598,7 @@ function callMember(instance: object, member: string, args: unknown[]): unknown
     return (fn as (...values: unknown[]) => unknown).apply(instance, args);
 }
 
-function backingMemberFor(instance: object, accessor: PropertyAccessor): string | undefined {
+function backingMemberFor(instance: object, accessor: DeclaredAccessor): string | undefined {
     if (accessor.hasGeneratedMember && !Object.hasOwn(instance, accessor.memberName)) {
         return undefined;
     }
@@ -414,6 +624,14 @@ function readCurrent(instance: object, accessor: PropertyAccessor): unknown {
         : (instance as Record<string, unknown>)[member];
 }
 
+function storeCurrent(instance: Record<symbol, unknown>, accessor: PropertyAccessor, value: unknown): void {
+    if (isParamExplicitlyNotified(accessor.flags)) {
+        writeStored(instance, accessor, value);
+    } else {
+        storeValue(instance, accessor, value);
+    }
+}
+
 function writeCurrent(instance: object, accessor: PropertyAccessor, value: unknown): void {
     const setter = accessor.delegate?.setter;
 
@@ -432,7 +650,7 @@ function writeCurrent(instance: object, accessor: PropertyAccessor, value: unkno
     const member = backingMemberFor(instance, accessor);
 
     if (member === undefined) {
-        storeValue(instance as Record<symbol, unknown>, accessor, value);
+        storeCurrent(instance as Record<symbol, unknown>, accessor, value);
 
         return;
     }
@@ -456,16 +674,17 @@ function makeSetProperty(dispatch: PropertyDispatch) {
     };
 }
 
-function assertCanonicalName(klass: AnyClass, name: string, propertyName: string): void {
-    const canonical = canonicalCase(name);
+const isCanonicalName = (name: string, propertyName: string): boolean =>
+    CANONICAL_NAME_PATTERN.test(propertyName) && toCamelIdentifier(propertyName) === toCamelIdentifier(name);
 
-    if (propertyName === canonical) {
+function assertCanonicalName(klass: AnyClass, name: string, propertyName: string): void {
+    if (isCanonicalName(name, propertyName)) {
         return;
     }
 
     throw new TypeError(
         `registerClass: ${klass.name} keys the property '${name}' to a GObject.ParamSpec named ` +
-        `'${propertyName}', which is the name GObject notifies under; name the ParamSpec '${canonical}'`,
+        `'${propertyName}', which is the name GObject notifies under; name the ParamSpec '${canonicalCase(name)}'`,
     );
 }
 
@@ -475,8 +694,8 @@ function assertCanonicalNames(klass: AnyClass, properties: Record<string, Proper
     }
 }
 
-function buildAccessor(klass: AnyClass, name: string, pspec: PropertySpec): PropertyAccessor {
-    const accessor: PropertyAccessor = {
+function buildAccessor(klass: AnyClass, name: string, pspec: PropertySpec): DeclaredAccessor {
+    const accessor: DeclaredAccessor = {
         ...checkFor(getHandle(pspec), name),
         memberName: camelCase(name),
         storage: Symbol(`gtkx:property:${name}`),
@@ -488,7 +707,7 @@ function buildAccessor(klass: AnyClass, name: string, pspec: PropertySpec): Prop
     return accessor;
 }
 
-function buildAccessors(source: PropertyDispatchSource): PropertyAccessor[] {
+function buildAccessors(source: PropertyDispatchSource): DeclaredAccessor[] {
     const { klass, properties } = source;
     assertCanonicalNames(klass, properties);
 
@@ -515,11 +734,35 @@ function interfaceDelegatesFor(adoptedTypes: bigint[]): Map<string, InterfacePro
     return delegates;
 }
 
+function recordDeclaredNames(klass: AnyClass, accessors: DeclaredAccessor[]): void {
+    const proto = klass.prototype as Record<PropertyKey, unknown>;
+    const inherited = proto[DECLARED_NAMES] as Record<string, string> | undefined;
+    const own: Record<string, string> = {};
+
+    for (const accessor of accessors) {
+        own[accessor.memberName] = accessor.propertyName;
+    }
+
+    Object.defineProperty(proto, DECLARED_NAMES, { value: { ...inherited, ...own }, enumerable: false });
+}
+
 function buildPropertyDispatch(source: PropertyDispatchSource): PropertyDispatch {
-    return {
-        accessors: buildAccessors(source),
-        delegates: interfaceDelegatesFor(source.adoptedTypes),
-    };
+    const declared = buildAccessors(source);
+    recordDeclaredNames(source.klass, declared);
+
+    return { accessors: [...declared], delegates: interfaceDelegatesFor(source.adoptedTypes) };
+}
+
+/**
+ * The GObject name a class registered with `registerClass` installed an accessor under, or
+ * `undefined` when the accessor names no property the class declared itself.
+ */
+function getDeclaredPropertyName(object: object, accessor: string): string | undefined {
+    const declared = (object as Record<PropertyKey, unknown>)[DECLARED_NAMES] as
+        | Record<string, string> |
+        undefined;
+
+    return declared?.[accessor];
 }
 
 function toNativeProperties(properties: Record<string, PropertySpec>): RegisterClassProperty[] {
@@ -531,10 +774,15 @@ function toNativeProperties(properties: Record<string, PropertySpec>): RegisterC
 
 export {
     buildPropertyDispatch,
+    coerceObjectProperty,
+    getDeclaredPropertyName,
+    isReadableProperty,
+    coercePropertyValue,
     constructPropertyFor,
     GET_PROPERTY_VFUNC,
     makeGetProperty,
     makeSetProperty,
+    newParamSpecOverride,
     SET_PROPERTY_VFUNC,
     toNativeProperties,
     type ConstructProperty,

package/src/regex.ts

@@ -0,0 +1,92 @@
+import { type Arg } from "./arg.js";
+import { booleanT, boxedT, bufferT, int32T, int64T, uint32T } from "./descriptors.js";
+import { fn } from "./fn.js";
+import { LIB } from "./library.js";
+import { getHandle } from "./registry.js";
+
+type MatchParams = {
+    regex: object;
+    subject: string | string[];
+    startPosition: number;
+    matchOptions: number;
+};
+
+const MATCH_ARGS: Arg[] = [
+    {
+        type: boxedT("GRegex", { ownership: "borrowed", sharedLibrary: LIB, getTypeFnName: "g_regex_get_type" }),
+    },
+    { type: bufferT },
+    { type: int64T },
+    { type: int32T },
+    { type: uint32T },
+    {
+        type: boxedT("GMatchInfo", { ownership: "full", sharedLibrary: LIB, getTypeFnName: "g_match_info_get_type" }),
+        direction: "out",
+    },
+];
+
+const gRegexMatchFull = fn(LIB, "g_regex_match_full", { args: MATCH_ARGS, returns: booleanT, canThrow: true });
+const gRegexMatchAllFull = fn(LIB, "g_regex_match_all_full", { args: MATCH_ARGS, returns: booleanT, canThrow: true });
+/* eslint-disable-next-line sonarjs/no-unused-collection -- keeps each subject's bytes alive alongside its match info */
+const subjectBytes: WeakMap<object, Uint8Array> = new WeakMap();
+const encoder = new TextEncoder();
+
+const flattenSubject = (subject: string | string[]): string =>
+    Array.isArray(subject) ? subject.join("") : subject;
+
+const matchWithSubject = <MatchInfo extends object>(
+    boundFn: (...inputs: unknown[]) => unknown,
+    { regex, subject, startPosition, matchOptions }: MatchParams,
+): [boolean, MatchInfo] => {
+    const bytes = encoder.encode(`${flattenSubject(subject)}\0`);
+
+    const result = boundFn(getHandle(regex), bytes, bytes.length - 1, startPosition, matchOptions) as [
+        boolean,
+        MatchInfo,
+    ];
+
+    subjectBytes.set(result[1], bytes);
+
+    return result;
+};
+
+/**
+ * Scans for a match of a compiled `GRegex` in the subject string, keeping the subject's bytes
+ * alive so the returned match info's fetch methods stay valid for as long as it is reachable.
+ *
+ * @param regex The compiled regex to scan with.
+ * @param subject The string to scan for matches.
+ * @param startPosition Starting index of the subject to match, in bytes.
+ * @param matchOptions Match options to apply.
+ * @returns Whether the subject matched, and the match info describing the match.
+ */
+function matchRegex<MatchInfo extends object>(
+    regex: object,
+    subject: string | string[],
+    startPosition: number,
+    matchOptions: number,
+): [boolean, MatchInfo] {
+    return matchWithSubject(gRegexMatchFull, { regex, subject, startPosition, matchOptions });
+}
+
+/**
+ * Scans for all possible matches of a compiled `GRegex` in the subject string using the DFA
+ * algorithm, including overlapping matches, keeping the subject's bytes alive so the returned
+ * match info's fetch methods stay valid for as long as it is reachable.
+ *
+ * @param regex The compiled regex to scan with.
+ * @param subject The string to scan for matches.
+ * @param startPosition Starting index of the subject to match, in bytes.
+ * @param matchOptions Match options to apply.
+ * @returns Whether the subject matched, and the match info describing the matches.
+ */
+function matchAllRegex<MatchInfo extends object>(
+    regex: object,
+    subject: string | string[],
+    startPosition: number,
+    matchOptions: number,
+): [boolean, MatchInfo] {
+    return matchWithSubject(gRegexMatchAllFull, { regex, subject, startPosition, matchOptions });
+}
+
+export { matchAllRegex, matchRegex };