@gtkx/runtime 1.2.2 → 1.3.0

package/src/object.ts

@@ -3,9 +3,9 @@ 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 { type ConstructProperty, constructPropertyFor } from "./properties.js";
+import { coercePropertyValue, type ConstructProperty, constructPropertyFor } from "./properties.js";
 import { getHandle, registerWrapper } from "./registry.js";
-import { fromValue, newValueForDescriptor, toValue } from "./value.js";
+import { fromValueForDescriptor, newValueForDescriptor, toValue } from "./value.js";
 
 /**
  * One construct property a wrapper class accepts: the canonical `GObject` name it is set under,
@@ -110,7 +110,7 @@ function constructPropertyForEntry(
         return constructPropertyFor(source.gtype, name, value, source.wrapper);
     }
 
-    return { name: binding[0], value: toValue(binding[1], value) };
+    return { name: binding[0], value: toValue(binding[1], coercePropertyValue(source.gtype, binding[0], value)) };
 }
 
 /**
@@ -123,17 +123,24 @@ function constructPropertyForEntry(
  * 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.
+ * numeric one of those lands 0 rather than being refused, and a number is fitted to
+ * the property first, as `coerceObjectProperty` does: truncated toward zero for a
+ * whole-number property and clamped to the range its `GObject.ParamSpec` allows.
  * 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.
+ * When construction returns an object that already has a wrapper — it reached
+ * JavaScript and was wrapped before `g_object_new` returned, for example a
+ * `Gtk.Window` observed through the toplevels list — that existing wrapper is
+ * returned instead of binding `wrapper`, so both references stay one object.
  *
  * @param gtype The GType of the object to construct.
  * @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.
+ * @returns The wrapper bound to the constructed object: `wrapper` itself, or
+ * the wrapper the object already had.
  */
-function newObjectWithProperties(gtype: bigint, props: object, wrapper: object): ExternalObject<Handle> {
+function newObjectWithProperties<T extends object>(gtype: bigint, props: object, wrapper: T): T {
     const names: string[] = [];
     const values: ExternalObject<Handle>[] = [];
     const bindings = constructBindingsFor(wrapper.constructor as AnyClass | undefined);
@@ -148,9 +155,13 @@ function newObjectWithProperties(gtype: bigint, props: object, wrapper: object):
         }
     }
 
-    newObject(gtype, names, values, wrapper, registerWrapper);
+    const existing = newObject(gtype, names, values, wrapper, registerWrapper);
 
-    return getHandle(wrapper);
+    if (existing !== null) {
+        return existing as T;
+    }
+
+    return wrapper;
 }
 
 /**
@@ -165,15 +176,16 @@ function getObjectProperty(obj: object, propertyName: string, descriptor: Descri
     const value = newValueForDescriptor(descriptor);
     gObjectGetProperty(getHandle(obj), propertyName, value);
 
-    return fromValue(value);
+    return fromValueForDescriptor(descriptor, value);
 }
 
 /**
  * Writes a JavaScript value to a GObject property, converting it to native form
  * 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`.
+ * property land 0, and a fractional number written to a whole-number property is truncated toward
+ * zero, where the same writes to a property installed through `registerClass` are refused with a
+ * `TypeError`.
  *
  * @param obj The object to write to.
  * @param propertyName The property name.

package/src/param-spec.ts

@@ -2,7 +2,7 @@ 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 { getHandle, getInstanceType } from "./registry.js";
 import {
     getStrvType,
     isTypedClass,
@@ -33,15 +33,17 @@ import {
 } from "./type.js";
 
 type ValueGuard = (value: unknown) => boolean;
-type ParamLayout = { flags: number; valueType: bigint };
+type ParamLayout = { flags: number; valueType: bigint; ownerType: bigint };
 
 const PARAM_READABLE = 1;
 const PARAM_WRITABLE = 2;
 const PARAM_CONSTRUCT_ONLY = 8;
 const PARAM_LAX_VALIDATION = 16;
+const PARAM_EXPLICIT_NOTIFY = 1 << 30;
 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 OWNER_TYPE_BYTE_OFFSET = 32;
 const LAYOUT_PROBE_NAME = "gtkx-param-layout";
 const INT8_MINIMUM = -128;
 const INT8_MAXIMUM = 127;
@@ -49,9 +51,9 @@ 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 INT64_MINIMUM: bigint = -(2n ** 63n);
+const INT64_MAXIMUM: bigint = 2n ** 63n - 1n;
+const UINT64_MAXIMUM: bigint = 2n ** 64n - 1n;
 
 const WRAPPED_FUNDAMENTALS: Set<bigint> = new Set([
     TYPE_BOXED,
@@ -62,6 +64,20 @@ const WRAPPED_FUNDAMENTALS: Set<bigint> = new Set([
 ]);
 
 const isWideUnsignedValue: ValueGuard = wideIntegerGuardFor(0n, UINT64_MAXIMUM);
+const MAX_SAFE: number = Number.MAX_SAFE_INTEGER;
+
+const WHOLE_NUMBER_RANGES: Map<bigint, [minimum: number, maximum: number]> = new Map([
+    [TYPE_CHAR, [INT8_MINIMUM, INT8_MAXIMUM]],
+    [TYPE_UCHAR, [0, UINT8_MAXIMUM]],
+    [TYPE_INT, [INT32_MINIMUM, INT32_MAXIMUM]],
+    [TYPE_UINT, [0, UINT32_MAXIMUM]],
+    [TYPE_ENUM, [INT32_MINIMUM, INT32_MAXIMUM]],
+    [TYPE_FLAGS, [0, UINT32_MAXIMUM]],
+    [TYPE_LONG, [-MAX_SAFE, MAX_SAFE]],
+    [TYPE_ULONG, [0, MAX_SAFE]],
+    [TYPE_INT64, [-MAX_SAFE, MAX_SAFE]],
+    [TYPE_UINT64, [0, MAX_SAFE]],
+]);
 
 const SCALAR_GUARDS: Map<bigint, ValueGuard> = new Map([
     [TYPE_BOOLEAN, isBooleanValue],
@@ -98,9 +114,49 @@ const getParamFlags = (pspec: ExternalObject<Handle>): number => read(pspec, uin
 const getParamValueType = (pspec: ExternalObject<Handle>): bigint =>
     read(pspec, biguint64T, VALUE_TYPE_BYTE_OFFSET) as bigint;
 
+const getParamOwnerType = (pspec: ExternalObject<Handle>): bigint =>
+    read(pspec, biguint64T, OWNER_TYPE_BYTE_OFFSET) as bigint;
+
+/**
+ * Reads the `GParamFlags` bitfield of a `GObject.ParamSpec`.
+ *
+ * @param spec The param spec wrapper to read.
+ * @returns The spec's flags.
+ */
+const getParamSpecFlags = (spec: object): number => {
+    assertParamLayout();
+
+    return getParamFlags(getHandle(spec));
+};
+
+/**
+ * Reads the GType of the values a `GObject.ParamSpec` describes.
+ *
+ * @param spec The param spec wrapper to read.
+ * @returns The GType of the spec's values.
+ */
+const getParamSpecValueType = (spec: object): bigint => {
+    assertParamLayout();
+
+    return getParamValueType(getHandle(spec));
+};
+
+/**
+ * Reads the GType a `GObject.ParamSpec` is installed on.
+ *
+ * @param spec The param spec wrapper to read.
+ * @returns The owning GType, or `TYPE_INVALID` while the spec is not installed on any type.
+ */
+const getParamSpecOwnerType = (spec: object): bigint => {
+    assertParamLayout();
+
+    return getParamOwnerType(getHandle(spec));
+};
+
 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 isParamExplicitlyNotified = (flags: number): boolean => (flags & PARAM_EXPLICIT_NOTIFY) !== 0;
 
 const wasParamValueModified = (pspec: ExternalObject<Handle>, value: ExternalObject<Handle>): boolean =>
     paramValueValidate(pspec, value) as boolean;
@@ -113,8 +169,18 @@ function isStringValue(value: unknown): boolean {
     return value == null || typeof value === "string";
 }
 
+function isStringArray(value: unknown[]): boolean {
+    for (const item of value) {
+        if (typeof item !== "string") {
+            return false;
+        }
+    }
+
+    return true;
+}
+
 function isStrvValue(value: unknown): boolean {
-    return value == null || (Array.isArray(value) && value.every((item) => typeof item === "string"));
+    return value == null || (Array.isArray(value) && isStringArray(value));
 }
 
 function isNumberValue(value: unknown): boolean {
@@ -193,7 +259,11 @@ function readProbeLayout(flags: number): ParamLayout {
     paramSpecRefSink(probe);
 
     try {
-        return { flags: getParamFlags(probe), valueType: getParamValueType(probe) };
+        return {
+            flags: getParamFlags(probe),
+            valueType: getParamValueType(probe),
+            ownerType: getParamOwnerType(probe),
+        };
     } finally {
         paramSpecUnref(probe);
     }
@@ -202,7 +272,11 @@ function readProbeLayout(flags: number): ParamLayout {
 function isLayoutIntact(flags: number): boolean {
     const layout = readProbeLayout(flags);
 
-    return (layout.flags & READ_FLAGS) === flags && layout.valueType === TYPE_BOOLEAN;
+    return (
+        (layout.flags & READ_FLAGS) === flags &&
+        layout.valueType === TYPE_BOOLEAN &&
+        layout.ownerType === TYPE_INVALID
+    );
 }
 
 function assertParamLayout(): void {
@@ -223,11 +297,23 @@ function assertParamLayout(): void {
 }
 
 export {
+    WHOLE_NUMBER_RANGES,
     getParamFlags,
+    getParamSpecFlags,
+    getParamSpecOwnerType,
+    getParamSpecValueType,
     getParamValueType,
+    INT32_MAXIMUM,
+    INT32_MINIMUM,
+    INT64_MAXIMUM,
+    INT64_MINIMUM,
     isParamConstructOnly,
+    isStringArray,
+    isParamExplicitlyNotified,
     isParamLaxlyValidated,
     isParamWritable,
+    resolveGtype,
+    UINT64_MAXIMUM,
     type ValueGuard,
     valueGuardFor,
     wasParamValueModified,

package/src/promisify.ts

@@ -13,6 +13,13 @@ type Settlement<R extends object, T> = {
     reject: (reason: Error) => void;
 };
 
+/** A finish result with its leading success boolean dropped: bare when one value remains, a tuple otherwise. */
+type TrimmedFinish<T> = T extends readonly [boolean, infer Only]
+    ? Only
+    : T extends readonly [boolean, ...infer Rest]
+        ? Rest
+        : never;
+
 const attachCreationStack = (error: unknown, creationStack: Error | undefined): void => {
     if (creationStack === undefined || !(error instanceof Error)) {
         return;
@@ -36,6 +43,25 @@ const settle = <R extends object, T>(settlement: Settlement<R, T>, asyncResult:
     }
 };
 
+/**
+ * Wraps a finish function whose result leads with the success boolean of a throwing C call,
+ * dropping that boolean: failure already surfaces as a thrown error, so the boolean is always
+ * `true`. A single remaining value is handed back bare, several stay a tuple. The finish result
+ * must carry at least one value beyond the boolean; a boolean-only finish needs no trimming.
+ *
+ * @param finish Extracts the boolean-led result from the async result passed to the completion callback.
+ * @returns A finish function resolving to the result without its leading boolean.
+ */
+const trimFinish =
+    <R extends object, T extends readonly [boolean, unknown, ...unknown[]]>(
+        finish: FinishResult<R, T>,
+    ): FinishResult<R, TrimmedFinish<T>> =>
+        (result: R): TrimmedFinish<T> => {
+            const [, ...rest] = finish(result);
+
+            return (rest.length === 1 ? rest[0] : rest) as TrimmedFinish<T>;
+        };
+
 /**
  * Wraps a GIO-style asynchronous function that takes a completion callback into a
  * promise, invoking the finish function to extract the result. Outside production,
@@ -64,4 +90,4 @@ const promisify = <R extends object, T>(
         });
     });
 
-export { promisify };
+export { promisify, trimFinish };

package/src/properties.ts

@@ -2,23 +2,33 @@ import type { ExternalObject, Handle, RegisterClassProperty } from "@gtkx/native
 import type { AnyClass } from "@gtkx/utils";
 import { camelCase, kebabCase } from "@gtkx/utils";
 import { bind } from "./bind.js";
-import { biguint64T, stringT, structT, voidT } from "./descriptors.js";
+import { biguint64T, fundamentalT, stringT, structT, voidT } from "./descriptors.js";
 import { LIB, PARAM_T, VALUE_T } from "./library.js";
 import {
     getParamFlags,
     getParamValueType,
     isParamConstructOnly,
+    isParamExplicitlyNotified,
     isParamLaxlyValidated,
     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,
@@ -72,12 +82,23 @@ 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 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 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("-", "_");
@@ -102,7 +123,7 @@ function checkFor(handle: ExternalObject<Handle>, name: string): PropertyCheck {
         handle,
         flags: getParamFlags(handle),
         valueType,
-        canHoldValue: valueGuardFor(valueType),
+        canHoldValue: valueGuardOverrideFor(valueType) ?? valueGuardFor(valueType),
         narrowValue: valueNarrowerFor(valueType),
     };
 }
@@ -113,6 +134,62 @@ function findPropertySpec(klass: ExternalObject<Handle>, name: string): External
     return found ?? (classFindProperty(klass, canonicalCase(name)) as ExternalObject<Handle> | 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 +290,97 @@ function constructValueFor(wrapper: object, check: PropertyCheck, value: unknown
     return { name: check.propertyName, value: checkedValueFor(wrapper, check, value) };
 }
 
+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,
@@ -414,6 +582,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 +608,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;
     }
@@ -531,10 +707,13 @@ function toNativeProperties(properties: Record<string, PropertySpec>): RegisterC
 
 export {
     buildPropertyDispatch,
+    coerceObjectProperty,
+    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 };