@gtkx/runtime 0.0.1 → 1.0.0-rc.2

package/src/descriptors.ts

@@ -0,0 +1,350 @@
+import type { ArrayKind, Descriptor, Ownership } from "@gtkx/native";
+import type { AnyClass } from "@gtkx/utils";
+
+type Int8Descriptor = Extract<Descriptor, { kind: "int8" }>;
+type Uint8Descriptor = Extract<Descriptor, { kind: "uint8" }>;
+type Int16Descriptor = Extract<Descriptor, { kind: "int16" }>;
+type Uint16Descriptor = Extract<Descriptor, { kind: "uint16" }>;
+type Int32Descriptor = Extract<Descriptor, { kind: "int32" }>;
+type Uint32Descriptor = Extract<Descriptor, { kind: "uint32" }>;
+type Int64Descriptor = Extract<Descriptor, { kind: "int64" }>;
+type Uint64Descriptor = Extract<Descriptor, { kind: "uint64" }>;
+type BigInt64Descriptor = Extract<Descriptor, { kind: "bigint64" }>;
+type BigUint64Descriptor = Extract<Descriptor, { kind: "biguint64" }>;
+type Float32Descriptor = Extract<Descriptor, { kind: "float32" }>;
+type Float64Descriptor = Extract<Descriptor, { kind: "float64" }>;
+type EnumDescriptor = Extract<Descriptor, { kind: "enum" }>;
+type FlagsDescriptor = Extract<Descriptor, { kind: "flags" }>;
+type BooleanDescriptor = Extract<Descriptor, { kind: "boolean" }>;
+type StringDescriptor = Extract<Descriptor, { kind: "string" }>;
+type ObjectDescriptor = Extract<Descriptor, { kind: "object" }>;
+type UnicharDescriptor = Extract<Descriptor, { kind: "unichar" }>;
+type VoidDescriptor = Extract<Descriptor, { kind: "void" }>;
+type BufferDescriptor = Extract<Descriptor, { kind: "buffer" }>;
+type BoxedDescriptor = Extract<Descriptor, { kind: "boxed" }>;
+type StructDescriptor = Extract<Descriptor, { kind: "struct" }> & { wrapperClass?: AnyClass };
+type FundamentalDescriptor = Extract<Descriptor, { kind: "fundamental" }> & { wrapperClass?: AnyClass };
+type ArrayDescriptor = Extract<Descriptor, { kind: "array" }>;
+type HashTableDescriptor = Extract<Descriptor, { kind: "hashtable" }>;
+type CallbackDescriptor = Extract<Descriptor, { kind: "callback" }>;
+type RefDescriptor = Extract<Descriptor, { kind: "ref" }>;
+type TypeDescriptor = BigUint64Descriptor & { type: true };
+
+type BoxedOptions = {
+    callerAllocated?: boolean;
+    inline?: boolean;
+    ownership?: Ownership;
+    sharedLibrary?: string;
+    getTypeFnName?: string;
+    freeFnName?: string;
+    size?: number;
+};
+
+type CallbackOptions = {
+    hasDestroy?: boolean;
+    userDataIndex?: number;
+    scope?: CallbackDescriptor["scope"];
+};
+
+type ArrayOptions = {
+    elementSize?: number | undefined;
+    sizeParamIndex?: number | undefined;
+    fixedSize?: number | undefined;
+};
+
+type FundamentalOptions = {
+    ownership?: Ownership;
+    typeName?: string;
+    wrapperClass?: AnyClass;
+    inline?: boolean;
+};
+
+type StructOptions = {
+    callerAllocated?: boolean;
+    inline?: boolean;
+    size?: number;
+    wrapperClass?: AnyClass;
+};
+
+const int8T: Int8Descriptor = { kind: "int8" };
+const uint8T: Uint8Descriptor = { kind: "uint8" };
+const int16T: Int16Descriptor = { kind: "int16" };
+const uint16T: Uint16Descriptor = { kind: "uint16" };
+const int32T: Int32Descriptor = { kind: "int32" };
+const uint32T: Uint32Descriptor = { kind: "uint32" };
+const int64T: Int64Descriptor = { kind: "int64" };
+const uint64T: Uint64Descriptor = { kind: "uint64" };
+const bigint64T: BigInt64Descriptor = { kind: "bigint64" };
+const biguint64T: BigUint64Descriptor = { kind: "biguint64" };
+const gtypeT: TypeDescriptor = { kind: "biguint64", type: true };
+const float32T: Float32Descriptor = { kind: "float32" };
+const float64T: Float64Descriptor = { kind: "float64" };
+const booleanT: BooleanDescriptor = { kind: "boolean" };
+const voidT: VoidDescriptor = { kind: "void" };
+const unicharT: UnicharDescriptor = { kind: "unichar" };
+const bufferT: BufferDescriptor = { kind: "buffer" };
+
+const stringT = (ownership: Ownership = "borrowed", length?: number): StringDescriptor =>
+    length === undefined ? { kind: "string", ownership } : { kind: "string", ownership, length };
+
+const objectT = (ownership: Ownership = "borrowed"): ObjectDescriptor => ({ kind: "object", ownership });
+
+const refT = (innerDescriptor: Descriptor, isInout = false): RefDescriptor =>
+    isInout ? { kind: "ref", innerDescriptor, inout: true } : { kind: "ref", innerDescriptor };
+
+const hashTableT = (
+    keyDescriptor: Descriptor,
+    valueDescriptor: Descriptor,
+    ownership: Ownership = "borrowed",
+): HashTableDescriptor => ({
+    kind: "hashtable",
+    keyDescriptor,
+    valueDescriptor,
+    ownership,
+});
+
+const enumT = (sharedLibrary: string, typeFnName: string, isSigned: boolean): EnumDescriptor => ({
+    kind: "enum",
+    sharedLibrary,
+    getTypeFnName: typeFnName,
+    signed: isSigned,
+});
+
+const flagsT = (sharedLibrary: string, typeFnName: string, isSigned: boolean): FlagsDescriptor => ({
+    kind: "flags",
+    sharedLibrary,
+    getTypeFnName: typeFnName,
+    signed: isSigned,
+});
+
+const applyBoxedNames = (result: BoxedDescriptor, options: BoxedOptions): void => {
+    if (options.sharedLibrary !== undefined) {
+        result.sharedLibrary = options.sharedLibrary;
+    }
+
+    if (options.getTypeFnName !== undefined) {
+        result.getTypeFnName = options.getTypeFnName;
+    }
+
+    if (options.freeFnName !== undefined) {
+        result.freeFnName = options.freeFnName;
+    }
+};
+
+const applyBoxedOptions = (result: BoxedDescriptor, options: BoxedOptions): void => {
+    applyBoxedNames(result, options);
+
+    if (options.callerAllocated) {
+        result.callerAllocated = true;
+    }
+
+    if (options.inline) {
+        result.inline = true;
+    }
+
+    if (options.size !== undefined) {
+        result.size = options.size;
+    }
+};
+
+const boxedT = (typeName: string, options: BoxedOptions = {}): BoxedDescriptor => {
+    const result: BoxedDescriptor = {
+        kind: "boxed",
+        ownership: options.ownership ?? "borrowed",
+        typeName,
+    };
+
+    applyBoxedOptions(result, options);
+
+    return result;
+};
+
+const structT = (ownership: Ownership = "borrowed", options: StructOptions = {}): StructDescriptor => {
+    const result: StructDescriptor = { kind: "struct", ownership };
+
+    if (options.size !== undefined) {
+        result.size = options.size;
+    }
+
+    if (options.wrapperClass !== undefined) {
+        result.wrapperClass = options.wrapperClass;
+    }
+
+    if (options.callerAllocated) {
+        result.callerAllocated = true;
+    }
+
+    if (options.inline) {
+        result.inline = true;
+    }
+
+    return result;
+};
+
+const fundamentalT = (
+    sharedLibrary: string,
+    refFnName: string,
+    unrefFnName: string,
+    options: FundamentalOptions = {},
+): FundamentalDescriptor => {
+    const ownership = options.ownership ?? "borrowed";
+    const result: FundamentalDescriptor = { kind: "fundamental", ownership, sharedLibrary, refFnName, unrefFnName };
+
+    if (options.typeName !== undefined) {
+        result.typeName = options.typeName;
+    }
+
+    if (options.wrapperClass !== undefined) {
+        result.wrapperClass = options.wrapperClass;
+    }
+
+    if (options.inline) {
+        result.inline = true;
+    }
+
+    return result;
+};
+
+const arrayT = (
+    itemDescriptor: Descriptor,
+    arrayKind: ArrayKind = "array",
+    ownership: Ownership = "borrowed",
+    options?: ArrayOptions,
+): ArrayDescriptor => {
+    const result: ArrayDescriptor = { kind: "array", itemDescriptor, arrayKind, ownership };
+
+    if (options?.elementSize !== undefined) {
+        result.elementSize = options.elementSize;
+    }
+
+    if (options?.sizeParamIndex !== undefined) {
+        result.sizeParamIndex = options.sizeParamIndex;
+    }
+
+    if (options?.fixedSize !== undefined) {
+        result.fixedSize = options.fixedSize;
+    }
+
+    return result;
+};
+
+const listT = (itemDescriptor: Descriptor, ownership: Ownership = "borrowed"): ArrayDescriptor =>
+    arrayT(itemDescriptor, "glist", ownership);
+
+const slistT = (itemDescriptor: Descriptor, ownership: Ownership = "borrowed"): ArrayDescriptor =>
+    arrayT(itemDescriptor, "gslist", ownership);
+
+const ptrArrayT = (itemDescriptor: Descriptor, ownership: Ownership = "borrowed"): ArrayDescriptor =>
+    arrayT(itemDescriptor, "gptrarray", ownership);
+
+const gArrayT = (
+    itemDescriptor: Descriptor,
+    ownership: Ownership = "borrowed",
+    elementSize?: number,
+): ArrayDescriptor =>
+    arrayT(itemDescriptor, "garray", ownership, elementSize === undefined ? undefined : { elementSize });
+
+const byteArrayT = (ownership: Ownership = "borrowed"): ArrayDescriptor =>
+    arrayT(uint8T, "gbytearray", ownership);
+
+const sizedArrayT = (
+    itemDescriptor: Descriptor,
+    sizeParamIndex: number,
+    ownership: Ownership = "borrowed",
+    elementSize?: number,
+): ArrayDescriptor => arrayT(itemDescriptor, "sized", ownership, { sizeParamIndex, elementSize });
+
+const fixedArrayT = (
+    itemDescriptor: Descriptor,
+    fixedSize: number,
+    ownership: Ownership = "borrowed",
+    elementSize?: number,
+): ArrayDescriptor => arrayT(itemDescriptor, "fixed", ownership, { fixedSize, elementSize });
+
+const callbackT = (
+    argDescriptors: Descriptor[],
+    returnDescriptor: Descriptor,
+    options?: CallbackOptions,
+): CallbackDescriptor => {
+    const result: CallbackDescriptor = { kind: "callback", argDescriptors, returnDescriptor };
+
+    if (options?.hasDestroy !== undefined) {
+        result.hasDestroy = options.hasDestroy;
+    }
+
+    if (options?.userDataIndex !== undefined) {
+        result.userDataIndex = options.userDataIndex;
+    }
+
+    if (options?.scope !== undefined) {
+        result.scope = options.scope;
+    }
+
+    return result;
+};
+
+export {
+    int8T,
+    uint8T,
+    int16T,
+    uint16T,
+    int32T,
+    uint32T,
+    int64T,
+    uint64T,
+    bigint64T,
+    biguint64T,
+    gtypeT,
+    float32T,
+    float64T,
+    booleanT,
+    voidT,
+    unicharT,
+    bufferT,
+    stringT,
+    objectT,
+    refT,
+    hashTableT,
+    enumT,
+    flagsT,
+    boxedT,
+    structT,
+    fundamentalT,
+    arrayT,
+    listT,
+    slistT,
+    ptrArrayT,
+    gArrayT,
+    byteArrayT,
+    sizedArrayT,
+    fixedArrayT,
+    callbackT,
+    type Int8Descriptor,
+    type Uint8Descriptor,
+    type Int16Descriptor,
+    type Uint16Descriptor,
+    type Int32Descriptor,
+    type Uint32Descriptor,
+    type Int64Descriptor,
+    type Uint64Descriptor,
+    type BigInt64Descriptor,
+    type BigUint64Descriptor,
+    type Float32Descriptor,
+    type Float64Descriptor,
+    type EnumDescriptor,
+    type FlagsDescriptor,
+    type BooleanDescriptor,
+    type StringDescriptor,
+    type ObjectDescriptor,
+    type UnicharDescriptor,
+    type VoidDescriptor,
+    type BufferDescriptor,
+    type BoxedDescriptor,
+    type StructDescriptor,
+    type FundamentalDescriptor,
+    type ArrayDescriptor,
+    type HashTableDescriptor,
+    type CallbackDescriptor,
+    type RefDescriptor,
+    type TypeDescriptor,
+};

package/src/error.ts

@@ -0,0 +1,58 @@
+import type { ExternalObject, Handle, Ref } from "@gtkx/native";
+import { getWrapperClass, wrapHandle } from "./registry.js";
+import { getErrorType, isTypedClass } from "./type.js";
+
+type ErrorLike = Error & {
+    domain: number;
+    code: number;
+};
+
+/**
+ * An error enum object carrying its member codes plus an `instanceof` check that
+ * matches wrapped GLib errors belonging to a specific error domain.
+ */
+type ErrorDomain<T extends Record<string, number>> = T & {
+    [Symbol.hasInstance]: (value: unknown) => value is ErrorLike;
+};
+
+function checkError(error: Ref): void {
+    if (error.value === null) {
+        return;
+    }
+
+    const gerror = wrapHandle(error.value as ExternalObject<Handle>, getWrapperClass(getErrorType())) as ErrorLike;
+    const callSite = new Error("gtkx call site");
+    const callerFrames = (callSite.stack ?? "").split("\n").slice(2);
+    gerror.stack = [`${gerror.name}: ${gerror.message}`, ...callerFrames].join("\n");
+    throw gerror;
+}
+
+const isError = (value: unknown): value is ErrorLike => isTypedClass(value) && value.__type__ === getErrorType();
+
+/**
+ * Builds an error domain enum object from its members and a lazy resolver for the
+ * domain quark, giving it an `instanceof` check that matches wrapped GLib errors of
+ * that domain.
+ *
+ * @param resolveDomain Called once, on first `instanceof` check, to obtain the domain quark.
+ * @param members The error code enum members to expose on the returned object.
+ */
+function createErrorDomain<const T extends Record<string, number>>(
+    resolveDomain: () => number,
+    members: T,
+): ErrorDomain<T> {
+    let domain: number | undefined;
+
+    const hasInstance = (value: unknown): value is ErrorLike => {
+        domain ??= resolveDomain();
+
+        return isError(value) && value.domain === domain;
+    };
+
+    const enumObject: Record<string, unknown> = { ...members };
+    Object.defineProperty(enumObject, Symbol.hasInstance, { value: hasInstance });
+
+    return enumObject as ErrorDomain<T>;
+}
+
+export { checkError, createErrorDomain, type ErrorDomain };

package/src/exit-hook.ts

@@ -0,0 +1,3 @@
+import { quit } from "./lifecycle.js";
+
+process.on("exit", quit);

package/src/fn.ts

@@ -0,0 +1,139 @@
+import type { Descriptor, Ref } from "@gtkx/native";
+import { type Arg, isCallerAllocatedArg, isInoutArg, isOutputArg, isRefArg } from "./arg.js";
+import { bind } from "./bind.js";
+import { wrapCallbackValue } from "./callback.js";
+import { boxedT, refT } from "./descriptors.js";
+import { checkError } from "./error.js";
+import { LIB } from "./library.js";
+import { fromNative } from "./native-value.js";
+import { getHandle } from "./registry.js";
+import { packTupleResult } from "./tuple.js";
+
+type FnSpec = {
+    args: Arg[];
+    returns: Descriptor;
+    throws?: boolean;
+};
+
+type ArgSpec = {
+    arg: Arg;
+    isRef: boolean;
+    isCallerAllocated: boolean;
+    consumesInput: boolean;
+    inputIndex: number;
+    isOutParam: boolean;
+};
+
+const buildNativeArgTypes = (args: Arg[], canThrow: boolean): Descriptor[] => {
+    const nativeArgTypes = args.map((argSpec) =>
+        argSpec.direction !== undefined && argSpec.callerAllocated !== true ? refT(argSpec.type) : argSpec.type,
+    );
+
+    if (canThrow) {
+        nativeArgTypes.push(
+            refT(boxedT("GError", { ownership: "full", sharedLibrary: LIB, getTypeFnName: "g_error_get_type" })),
+        );
+    }
+
+    return nativeArgTypes;
+};
+
+const buildArgSpecs = (args: Arg[]): ArgSpec[] => {
+    let inputCursor = 0;
+
+    return args.map((arg) => {
+        const isRef = isRefArg(arg);
+        const isConsumesInput = !isRef || isInoutArg(arg);
+        const isOutParam = isOutputArg(arg) && arg.consumed !== true;
+
+        return {
+            arg,
+            isRef,
+            isCallerAllocated: isCallerAllocatedArg(arg),
+            consumesInput: isConsumesInput,
+            inputIndex: isConsumesInput ? inputCursor++ : -1,
+            isOutParam,
+        };
+    });
+};
+
+const resolveCallerAllocated = (inputs: unknown[], inputIndex: number): unknown => {
+    const wrapper = inputs[inputIndex];
+
+    return wrapper == null ? wrapper : getHandle(wrapper);
+};
+
+const buildRefValue = (isInputConsumed: boolean, inputs: unknown[], inputIndex: number): Ref => ({
+    value: isInputConsumed ? inputs[inputIndex] : null,
+});
+
+const buildNativeValue = (spec: ArgSpec, inputs: unknown[]): unknown => {
+    const { arg, isRef, isCallerAllocated, consumesInput, inputIndex } = spec;
+
+    if (isCallerAllocated) {
+        return resolveCallerAllocated(inputs, inputIndex);
+    }
+
+    if (isRef) {
+        return buildRefValue(consumesInput, inputs, inputIndex);
+    }
+
+    if (arg.type.kind === "callback") {
+        return wrapCallbackValue(arg.type, inputs[inputIndex]);
+    }
+
+    return inputs[inputIndex];
+};
+
+const buildNativeValues = (plans: ArgSpec[], inputs: unknown[]): unknown[] =>
+    plans.map((plan) => buildNativeValue(plan, inputs));
+
+const readOutParams = (plans: ArgSpec[], inputs: unknown[], nativeValues: unknown[]): unknown[] => {
+    const outParams: unknown[] = [];
+
+    for (const [index, { arg, isCallerAllocated, inputIndex, isOutParam }] of plans.entries()) {
+        if (!isOutParam) {
+            continue;
+        }
+
+        outParams.push(
+            isCallerAllocated ? inputs[inputIndex] : fromNative(arg.type, (nativeValues[index] as Ref).value),
+        );
+    }
+
+    return outParams;
+};
+
+function fn(sharedLibrary: string, symbol: string, spec: FnSpec): (...inputs: unknown[]) => unknown {
+    const { args, returns: returnDescriptor, throws = false } = spec;
+    const nativeArgTypes = buildNativeArgTypes(args, throws);
+    const nativeFn = bind(sharedLibrary, symbol, nativeArgTypes, returnDescriptor);
+    const hasPrimary = returnDescriptor.kind !== "void";
+    const plans = buildArgSpecs(args);
+
+    const shape = (inputs: unknown[], nativeValues: unknown[], nativeResult: unknown): unknown => {
+        const primary = hasPrimary ? fromNative(returnDescriptor, nativeResult) : undefined;
+
+        return packTupleResult(readOutParams(plans, inputs, nativeValues), primary, hasPrimary);
+    };
+
+    if (throws) {
+        return (...inputs) => {
+            const nativeValues = buildNativeValues(plans, inputs);
+            const errorRef: Ref = { value: null };
+            nativeValues.push(errorRef);
+            const nativeResult = nativeFn(...nativeValues);
+            checkError(errorRef);
+
+            return shape(inputs, nativeValues, nativeResult);
+        };
+    }
+
+    return (...inputs) => {
+        const nativeValues = buildNativeValues(plans, inputs);
+
+        return shape(inputs, nativeValues, nativeFn(...nativeValues));
+    };
+}
+
+export { fn };

package/src/index.ts

@@ -0,0 +1,59 @@
+import "./exit-hook.js";
+
+export { createErrorDomain, type ErrorDomain } from "./error.js";
+export { type ApplicationLike, onExit, quit, quitApplication, runApplication } from "./lifecycle.js";
+export { offSignal, onceSignal, onSignal } from "./listeners.js";
+export { installMixins, type Mixin } from "./mixin.js";
+export { fromNative } from "./native-value.js";
+export { getObjectProperty, newObjectWithProperties, setObjectProperty } from "./object.js";
+export { type FinishResult, promisify } from "./promisify.js";
+export { registerClass } from "./register-class.js";
+export {
+    getHandle,
+    getInstanceType,
+    getWrapperClass,
+    registerInterface,
+    registerWrapperClass,
+    type StaticBase,
+    setHandle,
+    tryGetHandle,
+    wrapHandle,
+} from "./registry.js";
+export { connectSignal, emitSignal, getSignalBaseName, type SignalHandler } from "./signal.js";
+export { t } from "./t.js";
+export {
+    resolveType,
+    TYPE_BOOLEAN,
+    TYPE_BOXED,
+    TYPE_CHAR,
+    TYPE_DOUBLE,
+    TYPE_ENUM,
+    TYPE_FLAGS,
+    TYPE_FLOAT,
+    TYPE_GTYPE,
+    TYPE_INT,
+    TYPE_INT64,
+    TYPE_INTERFACE,
+    TYPE_INVALID,
+    TYPE_LONG,
+    TYPE_NONE,
+    TYPE_OBJECT,
+    TYPE_PARAM,
+    TYPE_POINTER,
+    TYPE_STRING,
+    TYPE_UCHAR,
+    TYPE_UINT,
+    TYPE_UINT64,
+    TYPE_ULONG,
+    TYPE_UNICHAR,
+    TYPE_VARIANT,
+    type TypedClass,
+    typeFromName,
+    typeInterfaces,
+    typeIsA,
+    typeName,
+    typeParent,
+    valueIsA,
+} from "./type.js";
+export { getBoxedValue, setBoxedValue } from "./value.js";
+export { alloc, type ExternalObject, type Handle, read, setWrapper, write } from "@gtkx/native";

package/src/internal.ts

@@ -0,0 +1,12 @@
+export { checkError, createErrorDomain } from "./error.js";
+export { registerClassType, resolveWrapperClass, wrapHandle } from "./registry.js";
+export { resolveType } from "./type.js";
+export {
+    fromValue,
+    getBoxedValue,
+    getValueType,
+    inoutValueForBoxedDescriptor,
+    newValueForDescriptor,
+    outValueForBoxedDescriptor,
+    toValue,
+} from "./value.js";

package/src/library.ts

@@ -0,0 +1,17 @@
+import { type BoxedDescriptor, boxedT, type FundamentalDescriptor, fundamentalT } from "./descriptors.js";
+
+const LIB = "libgobject-2.0.so.0,libglib-2.0.so.0";
+const VALUE_SIZE = 24;
+const VALUE_T: BoxedDescriptor = boxedT("GValue", { sharedLibrary: LIB, getTypeFnName: "g_value_get_type" });
+
+const PARAM_T: FundamentalDescriptor = fundamentalT(LIB, "g_param_spec_ref", "g_param_spec_unref", {
+    ownership: "borrowed",
+    typeName: "GParam",
+});
+
+const VARIANT_T: FundamentalDescriptor = fundamentalT(LIB, "g_variant_ref", "g_variant_unref", {
+    ownership: "borrowed",
+    typeName: "GVariant",
+});
+
+export { LIB, VALUE_SIZE, VALUE_T, PARAM_T, VARIANT_T };