@gtkx/runtime 1.2.2 → 1.4.0

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,50 @@ 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 isParamReadable = (flags: number): boolean => (flags & PARAM_READABLE) !== 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 +170,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 +260,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 +273,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 +298,24 @@ function assertParamLayout(): void {
 }
 
 export {
+    WHOLE_NUMBER_RANGES,
     getParamFlags,
+    getParamSpecFlags,
+    getParamSpecOwnerType,
+    getParamSpecValueType,
     getParamValueType,
+    INT32_MAXIMUM,
+    INT32_MINIMUM,
+    INT64_MAXIMUM,
+    INT64_MINIMUM,
     isParamConstructOnly,
+    isParamReadable,
+    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 };