@gtkx/codegen 1.0.0-rc.4 → 1.0.0

package/overrides/gobject/object.ts.ejs

@@ -1,22 +1,67 @@
-import { offSignal, onceSignal, onSignal } from "@gtkx/runtime";
-import { Object as GObject, signalHandlerDisconnect, type Type } from "../gobject.js";
+import { disconnectSignal, offSignal, onceSignal, onSignal } from "@gtkx/runtime";
+import { Object as GObject, type Type } from "../gobject.js";
 
 type Listener = (...args: unknown[]) => unknown;
 
 declare module "../gobject.js" {
     interface Object {
+        /** GType the instance's class is registered under, carried on the prototype. */
         __type__: Type;
 
+        /**
+         * Disconnects the handler `connect` returned the given id for.
+         *
+         * @param handlerId Id of the handler to disconnect.
+         */
         disconnect(handlerId: number): void;
 
+        /**
+         * Connects a handler that runs on every emission of `sigName`, remembering it so `off` can
+         * take the same callback back off again.
+         *
+         * @param sigName Signal to connect to.
+         * @param callback Handler invoked on each emission.
+         * @param isAfter Run the handler after the default handler rather than before it.
+         * @returns The same object, so calls chain.
+         */
         on(sigName: string, callback: (...args: unknown[]) => unknown, isAfter?: boolean): Object;
 
+        /**
+         * Connects a handler that runs at most once and disconnects itself after the first emission.
+         *
+         * @param sigName Signal to connect to.
+         * @param callback Handler invoked on the first emission.
+         * @param isAfter Run the handler after the default handler rather than before it.
+         * @returns The same object, so calls chain.
+         */
         once(sigName: string, callback: (...args: unknown[]) => unknown, isAfter?: boolean): Object;
 
+        /**
+         * Disconnects a handler previously connected with `on` or `once`, given the same callback.
+         *
+         * @param sigName Signal the handler was connected to.
+         * @param callback The handler that was connected.
+         * @returns The same object, so calls chain.
+         */
         off(sigName: string, callback: (...args: unknown[]) => unknown): Object;
 
+        /**
+         * Alias of `on`, for callers who prefer the DOM spelling.
+         *
+         * @param sigName Signal to connect to.
+         * @param callback Handler invoked on each emission.
+         * @param isAfter Run the handler after the default handler rather than before it.
+         * @returns The same object, so calls chain.
+         */
         addEventListener(sigName: string, callback: (...args: unknown[]) => unknown, isAfter?: boolean): Object;
 
+        /**
+         * Alias of `off`, for callers who prefer the DOM spelling.
+         *
+         * @param sigName Signal the handler was connected to.
+         * @param callback The handler that was connected.
+         * @returns The same object, so calls chain.
+         */
         removeEventListener(sigName: string, callback: (...args: unknown[]) => unknown): Object;
     }
 }
@@ -26,7 +71,7 @@ type GObjectWithConnect = GObject & {
 };
 
 GObject.prototype.disconnect = function disconnect(handlerId: number): void {
-    signalHandlerDisconnect(this, BigInt(handlerId));
+    disconnectSignal(this, handlerId);
 };
 
 function onImpl(this: GObjectWithConnect, sigName: string, callback: Listener, isAfter?: boolean): GObject {

package/overrides/gobject/value.ts.ejs

@@ -1,6 +1,13 @@
 import { getBoxedValue, getHandle, setBoxedValue } from "@gtkx/runtime";
 import { type Type, Value } from "../gobject.js";
 
+/**
+ * Allocates a `Value`, initializes it to `gtype`, and hands it to `populate` to fill in.
+ *
+ * @param gtype GType the value holds.
+ * @param populate Called with the initialized value to write the contents.
+ * @returns The populated value.
+ */
 export const buildValue = (gtype: Type, populate: (value: Value) => void): Value => {
     const value = new Value();
     value.init(gtype);

package/overrides/graphene/structs.ts.ejs

@@ -1,37 +1,92 @@
 import { Point as GeneratedPoint, Rect as GeneratedRect, Size as GeneratedSize } from "../graphene.js";
 
+/**
+ * Allocates a new `Point` and initializes it to the given coordinates.
+ *
+ * @param x the X coordinate
+ * @param y the Y coordinate
+ * @returns the initialized point
+ */
 const createPoint = (x: number, y: number): GeneratedPoint => {
     const point = GeneratedPoint.alloc();
     point.init(x, y);
     return point;
 };
 
+/**
+ * Allocates a new `Rect` and initializes it to the given origin and size.
+ *
+ * @param x the X coordinate of the origin
+ * @param y the Y coordinate of the origin
+ * @param width the width of the rectangle
+ * @param height the height of the rectangle
+ * @returns the initialized rectangle
+ */
 const createRect = (x: number, y: number, width: number, height: number): GeneratedRect => {
     const rect = GeneratedRect.alloc();
     rect.init(x, y, width, height);
     return rect;
 };
 
+/**
+ * Allocates a new `Size` and initializes it to the given width and height.
+ *
+ * @param width the width
+ * @param height the height
+ * @returns the initialized size
+ */
 const createSize = (width: number, height: number): GeneratedSize => {
     const size = GeneratedSize.alloc();
     size.init(width, height);
     return size;
 };
 
+/** A point with two coordinates. */
 export const Point: typeof GeneratedPoint & { create: typeof createPoint } = Object.assign(GeneratedPoint, {
     create: createPoint,
 });
 
+/** A point with two coordinates. */
 export type Point = GeneratedPoint;
 
+/**
+ * The location and size of a rectangle region.
+ *
+ * The width and height of a `graphene_rect_t` can be negative; for instance,
+ * a `graphene_rect_t` with an origin of [ 0, 0 ] and a size of [ 10, 10 ] is
+ * equivalent to a `graphene_rect_t` with an origin of [ 10, 10 ] and a size
+ * of [ -10, -10 ].
+ *
+ * Application code can normalize rectangles using `graphene_rect_normalize()`;
+ * this function will ensure that the width and height of a rectangle are
+ * positive values. All functions taking a `graphene_rect_t` as an argument
+ * will internally operate on a normalized copy; all functions returning a
+ * `graphene_rect_t` will always return a normalized rectangle.
+ */
 export const Rect: typeof GeneratedRect & { create: typeof createRect } = Object.assign(GeneratedRect, {
     create: createRect,
 });
 
+/**
+ * The location and size of a rectangle region.
+ *
+ * The width and height of a `graphene_rect_t` can be negative; for instance,
+ * a `graphene_rect_t` with an origin of [ 0, 0 ] and a size of [ 10, 10 ] is
+ * equivalent to a `graphene_rect_t` with an origin of [ 10, 10 ] and a size
+ * of [ -10, -10 ].
+ *
+ * Application code can normalize rectangles using `graphene_rect_normalize()`;
+ * this function will ensure that the width and height of a rectangle are
+ * positive values. All functions taking a `graphene_rect_t` as an argument
+ * will internally operate on a normalized copy; all functions returning a
+ * `graphene_rect_t` will always return a normalized rectangle.
+ */
 export type Rect = GeneratedRect;
 
+/** A size. */
 export const Size: typeof GeneratedSize & { create: typeof createSize } = Object.assign(GeneratedSize, {
     create: createSize,
 });
 
+/** A size. */
 export type Size = GeneratedSize;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gtkx/codegen",
-  "version": "1.0.0-rc.4",
+  "version": "1.0.0",
   "description": "Generates the typed GTKX bindings and API reference from GIR and OpenGL registry data",
   "keywords": [
     "gtkx",
@@ -44,11 +44,11 @@
     "node": ">=24"
   },
   "dependencies": {
-    "@types/node": "^26.1.2",
+    "@types/node": "^26.2.0",
     "fast-xml-parser": "^5.10.1",
     "typescript": "^6.0.3",
-    "@gtkx/react": "1.0.0-rc.4",
-    "@gtkx/utils": "1.0.0-rc.4"
+    "@gtkx/utils": "1.0.0",
+    "@gtkx/react": "1.0.0"
   },
   "scripts": {
     "release": "tsx ../../scripts/release-package.ts"

package/src/analysis/descriptor-render.ts

@@ -48,10 +48,12 @@ import {
     tUint64,
     tVoid,
 } from "./descriptor.js";
+import { carrayFor, isUnboundedArray, primitiveCategoryFor } from "./type-shape.js";
 
 type RenderDescriptorOptions = {
     argIndexOffset?: number;
     argIndexMap?: Map<number, number> | undefined;
+    hasOutIndirection?: boolean;
     isCallerAllocated?: boolean;
     isInline?: boolean;
     isNewlyCreated?: boolean;
@@ -60,6 +62,7 @@ type RenderDescriptorOptions = {
 type ArgIndexOptions = {
     argIndexOffset: number;
     argIndexMap: Map<number, number> | undefined;
+    hasOutIndirection: boolean;
 };
 
 type RecordPlacement = {
@@ -122,15 +125,8 @@ const transferOwnership = (transfer: ParameterTransfer): Ownership => {
 const deriveElementTransfer = (transfer: ParameterTransfer): ParameterTransfer =>
     transfer === "container" ? "none" : transfer;
 
-const isVoidRef = (library: Library, ref: TypeId | undefined): boolean => {
-    if (ref === undefined) {
-        return true;
-    }
-
-    const type = library.typeFor(ref);
-
-    return type?.kind === "primitive" && type.category === "void";
-};
+const isVoidRef = (library: Library, ref: TypeId | undefined): boolean =>
+    ref === undefined || primitiveCategoryFor(library, ref) === "void";
 
 const isInlineCallbackRef = (library: Library, ref: TypeId | undefined): boolean =>
     ref !== undefined && library.typeFor(ref)?.kind === "callback" && library.nameFor(ref) === undefined;
@@ -138,6 +134,12 @@ const isInlineCallbackRef = (library: Library, ref: TypeId | undefined): boolean
 const shouldOmitPrimaryReturn = (library: Library, returnValue: GirReturnValue): boolean =>
     isVoidRef(library, returnValue.type) || returnValue.skip;
 
+const argIndexOptions = (options: RenderDescriptorOptions): ArgIndexOptions => ({
+    argIndexOffset: options.argIndexOffset ?? 0,
+    argIndexMap: options.argIndexMap,
+    hasOutIndirection: options.hasOutIndirection === true,
+});
+
 const renderDescriptor = (
     context: ModuleContext,
     ref: TypeId | undefined,
@@ -148,8 +150,7 @@ const renderDescriptor = (
         return tVoid;
     }
 
-    const { argIndexOffset = 0 } = options;
-    const indexOptions: ArgIndexOptions = { argIndexOffset, argIndexMap: options.argIndexMap };
+    const indexOptions = argIndexOptions(options);
     const ownership = transferOwnership(transfer);
     const type = context.library.typeFor(ref);
 
@@ -255,8 +256,19 @@ const isScalarRef = (library: Library, ref: TypeId | undefined): boolean => {
     return type !== undefined && isScalarType(library, type);
 };
 
+const isStrvRef = (library: Library, ref: TypeId | undefined): boolean => {
+    const type = carrayFor(library, ref);
+
+    if (type === undefined) {
+        return false;
+    }
+
+    return isUnboundedArray(type) && primitiveCategoryFor(library, type.element) === "string";
+};
+
 const isCellInout = (library: Library, parameter: GirParameter): boolean =>
-    isInoutParameter(parameter) && isScalarRef(library, parameter.type);
+    isInoutParameter(parameter) &&
+    (isScalarRef(library, parameter.type) || isStrvRef(library, parameter.type));
 
 const renderParamDescriptor = (
     context: ModuleContext,
@@ -264,12 +276,14 @@ const renderParamDescriptor = (
     ref: TypeId | undefined,
     argIndex: Partial<ArgIndexOptions> = {},
 ): string => {
+    const behindRef: RenderDescriptorOptions = { ...argIndex, hasOutIndirection: true };
+
     if (isCellInout(context.library, parameter)) {
-        return tRef(renderDescriptor(context, ref, parameter.transferOwnership, argIndex), true);
+        return tRef(renderDescriptor(context, ref, parameter.transferOwnership, behindRef), true);
     }
 
     if (isOutParameter(parameter)) {
-        return tRef(renderDescriptor(context, ref, parameter.transferOwnership, argIndex));
+        return tRef(renderDescriptor(context, ref, parameter.transferOwnership, behindRef));
     }
 
     return renderDescriptor(context, ref, parameter.transferOwnership, {
@@ -303,6 +317,10 @@ const callbackOptionsArg = (owningParameter: GirParameter, userDataIndex: number
         options.push("hasDestroy: true");
     }
 
+    if (owningParameter.closureIndex !== undefined) {
+        options.push("hasUserData: true");
+    }
+
     if (userDataIndex !== undefined) {
         options.push(`userDataIndex: ${String(userDataIndex)}`);
     }
@@ -458,10 +476,11 @@ const fundamentalAncestor = (
 const classSelfDescriptor = (
     context: ModuleContext,
     type: Extract<EntityType, { kind: "class" | "interface" }>,
+    ownership: Ownership,
 ): string => {
     const ancestor = fundamentalAncestor(context, type);
 
-    return ancestor === undefined ? tObject("borrowed") : renderFundamental({ ...ancestor, ownership: "borrowed" });
+    return ancestor === undefined ? tObject(ownership) : renderFundamental({ ...ancestor, ownership });
 };
 
 const renderSelfDescriptor = (context: ModuleContext, instance: GirParameter): string => {
@@ -478,7 +497,7 @@ const renderSelfDescriptor = (context: ModuleContext, instance: GirParameter): s
     }
 
     if (isClassOrInterface(type)) {
-        return classSelfDescriptor(context, type);
+        return classSelfDescriptor(context, type, transferOwnership(instance.transferOwnership));
     }
 
     if (type.kind === "record") {
@@ -659,8 +678,9 @@ const arrayExpression = (
     }
 
     const ownership = transferOwnership(transfer);
-    const element = renderDescriptor(context, ref.element, deriveElementTransfer(transfer), options);
-    const size = inlineElementSize(context, ref.element, ref.elementCType);
+    const elementOptions: ArgIndexOptions = { ...options, hasOutIndirection: false };
+    const element = renderDescriptor(context, ref.element, deriveElementTransfer(transfer), elementOptions);
+    const size = inlineElementSize(context, ref, options.hasOutIndirection);
 
     if (ref.lengthParameterIndex !== undefined) {
         return tSizedArray(element, mapArgIndex(options, ref.lengthParameterIndex), ownership, size);
@@ -683,20 +703,18 @@ const recordInlineSize = (context: ModuleContext, record: ResolvedRecord): numbe
     return size > 0 ? size : undefined;
 };
 
-const inlineElementSize = (
-    context: ModuleContext,
-    element: TypeId | undefined,
-    elementCType: string | undefined,
-): number | undefined => {
-    if (element === undefined) {
-        return undefined;
-    }
+const elementPointerDepth = (elementCType: string | undefined, hasOutIndirection: boolean): number => {
+    const declared = elementCType === undefined ? 0 : elementCType.split("*").length - 1;
+
+    return hasOutIndirection ? declared - 1 : declared;
+};
 
-    if (elementCType?.includes("*")) {
+const inlineElementSize = (context: ModuleContext, ref: CArrayType, hasOutIndirection: boolean): number | undefined => {
+    if (elementPointerDepth(ref.elementCType, hasOutIndirection) > 0) {
         return undefined;
     }
 
-    const type = context.library.typeFor(element);
+    const type = context.library.typeFor(ref.element);
 
     if (type?.kind !== "record") {
         return undefined;
@@ -724,6 +742,7 @@ export {
     renderDescriptor,
     isScalarRef,
     isCellInout,
+    recordInlineSize,
     renderParamDescriptor,
     renderCallbackType,
     renderSelfDescriptor,

package/src/analysis/descriptor.ts

@@ -293,8 +293,5 @@ export {
     tFn,
     type Ownership,
     type ScalarDescriptorName,
-    type BoxedOptions,
-    type StructOptions,
-    type FundamentalOptions,
     type ListDescriptorName,
 };

package/src/analysis/inheritance.ts

@@ -5,9 +5,10 @@ import type { Library } from "../gir/library.js";
 import type { GirProperty } from "../gir/property.js";
 import type { TypeId } from "../gir/type-id.js";
 import type { ModuleContext } from "../writer/context.js";
-import { ancestorChain, type ResolvedAncestor, resolveInterface } from "../gir/ancestry.js";
+import { ancestorChain, type ResolvedAncestor, resolveInterfaces } from "../gir/ancestry.js";
 import { methodExportName } from "../store/gi/method.js";
 import { resolveAccessorType } from "../store/gi/property-accessor.js";
+import { vfuncMemberNames } from "../store/gi/vtable.js";
 import { inputParameters } from "./param-structure.js";
 import { renderTsType } from "./ts-type.js";
 
@@ -45,29 +46,11 @@ const RESERVED_SIGNAL_MEMBERS = new Set([
     "removeEventListener",
 ]);
 
-const resolveImplementedInterface = (
-    context: AncestryContext,
-    name: string,
-    defaultNamespace: string = context.namespace.name,
-): ResolvedAncestor | undefined => resolveInterface(context.library, defaultNamespace, name);
-
 const resolveDirectInterfaces = (
     context: AncestryContext,
     klass: GirClass,
     defaultNamespace: string,
-): ResolvedAncestor[] => {
-    const interfaces: ResolvedAncestor[] = [];
-
-    for (const implementName of klass.implements) {
-        const iface = resolveImplementedInterface(context, implementName, defaultNamespace);
-
-        if (iface !== undefined) {
-            interfaces.push(iface);
-        }
-    }
-
-    return interfaces;
-};
+): ResolvedAncestor[] => resolveInterfaces(context.library, defaultNamespace, klass.implements);
 
 const resolvePrerequisiteReference = (context: ModuleContext, name: string): string | undefined => {
     const resolved = context.library.resolveType(context.namespace.name, name);
@@ -221,25 +204,45 @@ const mergeOmissionName = (
     return ancestor.returnType !== returnType || ancestor.arity !== arity ? name : undefined;
 };
 
-const collectInterfaceMergeOmissions = (
+const classChainVfuncNames = (context: ModuleContext, klass: GirClass): Set<string> => {
+    const names: Set<string> = new Set(vfuncMemberNames(context, context.namespace.name, klass));
+
+    forEachAncestor(context, klass, (ancestor) => {
+        for (const name of vfuncMemberNames(context, ancestor.namespaceName, ancestor.klass)) {
+            names.add(name);
+        }
+    });
+
+    return names;
+};
+
+const methodMergeOmissions = (context: ModuleContext, klass: GirClass, iface: GirClass): string[] => {
+    const ancestors = ancestorClassMethodSignatures(context, klass);
+
+    return iface.methods
+        .map((method) => mergeOmissionName(context, method, ancestors))
+        .filter((name): name is string => name !== undefined);
+};
+
+const vfuncMergeOmissions = (
     context: ModuleContext,
     klass: GirClass,
     iface: { klass: GirClass; namespaceName: string },
 ): string[] => {
-    const ancestors = ancestorClassMethodSignatures(context, klass);
-    const omissions: string[] = [];
+    const claimed = classChainVfuncNames(context, klass);
 
-    for (const method of iface.klass.methods) {
-        const name = mergeOmissionName(context, method, ancestors);
-
-        if (name !== undefined) {
-            omissions.push(name);
-        }
-    }
-
-    return omissions;
+    return vfuncMemberNames(context, iface.namespaceName, iface.klass).filter((name) => claimed.has(name));
 };
 
+const collectInterfaceMergeOmissions = (
+    context: ModuleContext,
+    klass: GirClass,
+    iface: { klass: GirClass; namespaceName: string },
+): string[] => [
+    ...methodMergeOmissions(context, klass, iface.klass),
+    ...vfuncMergeOmissions(context, klass, iface),
+];
+
 const collectInheritedPropertyTypes = (context: ModuleContext, klass: GirClass): Map<string, string> => {
     const types: Map<string, string> = new Map();
 
@@ -416,7 +419,6 @@ const enumIdentity = (context: ModuleContext, ref: TypeId | undefined): string |
 };
 
 export {
-    resolveImplementedInterface,
     resolvePrerequisiteReference,
     forEachAncestor,
     collectInterfaceProperties,
@@ -425,6 +427,5 @@ export {
     collectInheritedMethods,
     conflictRename,
     reservedSignalMemberRename,
-    type OwnedProperty,
     type InheritedMethods,
 };

package/src/analysis/nul-terminated-bytes.ts

@@ -0,0 +1,31 @@
+import type { Library } from "../gir/library.js";
+import type { GirCallable, GirParameter } from "../gir/parameter.js";
+import type { TypeId } from "../gir/type-id.js";
+import { isOutParameter } from "../gir/parameter.js";
+import { carrayFor, isUnboundedArray, primitiveCategoryFor } from "./type-shape.js";
+
+const BYTE_CATEGORIES: Set<string> = new Set(["int8", "uint8"]);
+const CHAR_POINTER = /char\s*\*/;
+
+const isByteElement = (library: Library, element: TypeId): boolean => {
+    const category = primitiveCategoryFor(library, element);
+
+    return category !== undefined && BYTE_CATEGORIES.has(category);
+};
+
+const isNulTerminatedBytes = (library: Library, ref: TypeId | undefined): boolean => {
+    const type = carrayFor(library, ref);
+
+    if (type?.arrayCType === undefined || !CHAR_POINTER.test(type.arrayCType)) {
+        return false;
+    }
+
+    return isUnboundedArray(type) && isByteElement(library, type.element);
+};
+
+const nulTerminatedByteParams = (library: Library, callable: GirCallable): GirParameter[] =>
+    callable.parameters.filter(
+        (parameter) => !isOutParameter(parameter) && isNulTerminatedBytes(library, parameter.type),
+    );
+
+export { nulTerminatedByteParams };