@gtkx/gir 0.19.0 → 0.21.0

package/src/internal/raw-types.ts

@@ -1,22 +1,23 @@
+import type { ContainerType } from "../model/type.js";
+
 /**
- * Raw GIR type definitions.
- *
- * These types represent the structure of parsed GIR XML data before normalization.
- * They are internal to the @gtkx/gir package and not exported publicly.
- *
- * @internal
+ * A dependency declared via `<include>` in a GIR file.
  */
-
-import type { ContainerType } from "../types.js";
-
-export type { ContainerType };
+export type RawDependency = {
+    name: string;
+    version: string;
+};
 
 /**
- * Represents a parsed GIR namespace (library).
- *
- * Contains all type definitions from a single GIR file, including
- * classes, interfaces, functions, enums, records, and callbacks.
+ * Lightweight header extracted from a GIR file without full parsing.
+ * Used to build the dependency graph before committing to full XML parsing.
  */
+export type RawRepositoryHeader = {
+    namespaceName: string;
+    namespaceVersion: string;
+    dependencies: RawDependency[];
+};
+
 export type RawNamespace = {
     name: string;
     version: string;
@@ -34,45 +35,6 @@ export type RawNamespace = {
     doc?: string;
 };
 
-/**
- * A constant value defined in a GIR namespace.
- */
-export type RawConstant = {
-    name: string;
-    cType: string;
-    value: string;
-    type: RawType;
-    doc?: string;
-};
-
-/**
- * A callback type definition (function pointer type).
- */
-export type RawCallback = {
-    name: string;
-    cType: string;
-    returnType: RawType;
-    parameters: RawParameter[];
-    doc?: string;
-};
-
-/**
- * A GObject interface definition.
- */
-export type RawInterface = {
-    name: string;
-    cType: string;
-    glibTypeName?: string;
-    prerequisites: string[];
-    methods: RawMethod[];
-    properties: RawProperty[];
-    signals: RawSignal[];
-    doc?: string;
-};
-
-/**
- * A GObject class definition.
- */
 export type RawClass = {
     name: string;
     cType: string;
@@ -93,9 +55,17 @@ export type RawClass = {
     doc?: string;
 };
 
-/**
- * A GLib record (boxed type or struct).
- */
+export type RawInterface = {
+    name: string;
+    cType: string;
+    glibTypeName?: string;
+    prerequisites: string[];
+    methods: RawMethod[];
+    properties: RawProperty[];
+    signals: RawSignal[];
+    doc?: string;
+};
+
 export type RawRecord = {
     name: string;
     cType: string;
@@ -113,21 +83,44 @@ export type RawRecord = {
     doc?: string;
 };
 
-/**
- * A field within a record or class.
- */
-export type RawField = {
+export type RawEnumeration = {
+    name: string;
+    cType: string;
+    members: RawEnumerationMember[];
+    glibGetType?: string;
+    doc?: string;
+};
+
+export type RawEnumerationMember = {
+    name: string;
+    value: string;
+    cIdentifier: string;
+    doc?: string;
+};
+
+export type RawCallback = {
+    name: string;
+    cType: string;
+    returnType: RawType;
+    parameters: RawParameter[];
+    doc?: string;
+};
+
+export type RawConstant = {
     name: string;
+    cType: string;
+    value: string;
     type: RawType;
-    writable?: boolean;
-    readable?: boolean;
-    private?: boolean;
     doc?: string;
 };
 
-/**
- * A method on a class, interface, or record.
- */
+export type RawAlias = {
+    name: string;
+    cType: string;
+    targetType: RawType;
+    doc?: string;
+};
+
 export type RawMethod = {
     name: string;
     cIdentifier: string;
@@ -137,15 +130,11 @@ export type RawMethod = {
     throws?: boolean;
     doc?: string;
     returnDoc?: string;
-    /** For async methods, the name of the corresponding finish function */
     finishFunc?: string;
     shadows?: string;
     shadowedBy?: string;
 };
 
-/**
- * A constructor for a class or record.
- */
 export type RawConstructor = {
     name: string;
     cIdentifier: string;
@@ -158,9 +147,6 @@ export type RawConstructor = {
     shadowedBy?: string;
 };
 
-/**
- * A standalone function or static method.
- */
 export type RawFunction = {
     name: string;
     cIdentifier: string;
@@ -173,9 +159,6 @@ export type RawFunction = {
     shadowedBy?: string;
 };
 
-/**
- * A parameter to a function, method, or callback.
- */
 export type RawParameter = {
     name: string;
     type: RawType;
@@ -183,19 +166,13 @@ export type RawParameter = {
     callerAllocates?: boolean;
     nullable?: boolean;
     optional?: boolean;
-    scope?: "async" | "call" | "notified";
+    scope?: "async" | "call" | "notified" | "forever";
     closure?: number;
     destroy?: number;
     transferOwnership?: "none" | "full" | "container";
     doc?: string;
 };
 
-/**
- * A type reference in GIR.
- *
- * Type names may be unqualified (e.g., "Widget") for local types
- * or qualified (e.g., "GObject.Object") for cross-namespace references.
- */
 export type RawType = {
     name: string;
     cType?: string;
@@ -210,9 +187,6 @@ export type RawType = {
     fixedSize?: number;
 };
 
-/**
- * A GObject property definition.
- */
 export type RawProperty = {
     name: string;
     type: RawType;
@@ -225,9 +199,6 @@ export type RawProperty = {
     doc?: string;
 };
 
-/**
- * A GObject signal definition.
- */
 export type RawSignal = {
     name: string;
     when?: "first" | "last" | "cleanup";
@@ -236,33 +207,11 @@ export type RawSignal = {
     doc?: string;
 };
 
-/**
- * An enumeration or bitfield definition.
- */
-export type RawEnumeration = {
-    name: string;
-    cType: string;
-    members: RawEnumerationMember[];
-    glibGetType?: string;
-    doc?: string;
-};
-
-/**
- * A member of an enumeration or bitfield.
- */
-export type RawEnumerationMember = {
-    name: string;
-    value: string;
-    cIdentifier: string;
-    doc?: string;
-};
-
-/**
- * A type alias definition.
- */
-export type RawAlias = {
+export type RawField = {
     name: string;
-    cType: string;
-    targetType: RawType;
+    type: RawType;
+    writable?: boolean;
+    readable?: boolean;
+    private?: boolean;
     doc?: string;
 };

package/src/intrinsics.ts

@@ -30,6 +30,7 @@ export const INTRINSIC_TYPES = new Set([
     "gulong",
     "gsize",
     "guintptr",
+    "gunichar",
     "gfloat",
     "gdouble",
     "gpointer",
@@ -47,6 +48,11 @@ export const INTRINSIC_TYPES = new Set([
     "double",
     "size_t",
     "ssize_t",
+    "time_t",
+    "pid_t",
+    "uid_t",
+    "int32",
+    "long double",
 ]);
 
 /**
@@ -96,6 +102,7 @@ export const NUMERIC_TYPES = new Set([
     "goffset",
     "gintptr",
     "guintptr",
+    "gunichar",
     "gfloat",
     "gdouble",
     "int",

package/src/model/alias.ts

@@ -0,0 +1,31 @@
+import type { GirType } from "./type.js";
+
+/**
+ * Type alias definition.
+ */
+export class GirAlias {
+    readonly name: string;
+    readonly qualifiedName: string;
+    readonly cType: string;
+    readonly targetType: GirType;
+    readonly doc?: string;
+
+    constructor(data: {
+        name: string;
+        qualifiedName: string;
+        cType: string;
+        targetType: GirType;
+        doc?: string;
+    }) {
+        this.name = data.name;
+        this.qualifiedName = data.qualifiedName;
+        this.cType = data.cType;
+        this.targetType = data.targetType;
+        this.doc = data.doc;
+    }
+
+    /** True if this alias points to a non-intrinsic, non-array type (likely a record). */
+    isRecordAlias(): boolean {
+        return !this.targetType.isIntrinsic() && !this.targetType.isArray;
+    }
+}

package/src/model/callables.ts

@@ -0,0 +1,172 @@
+import type { GirParameter } from "./parameter.js";
+import type { GirType } from "./type.js";
+
+/**
+ * Method on a class, interface, or record.
+ */
+export class GirMethod {
+    readonly name: string;
+    readonly cIdentifier: string;
+    readonly returnType: GirType;
+    readonly parameters: GirParameter[];
+    readonly instanceParameter?: GirParameter;
+    readonly throws: boolean;
+    readonly doc?: string;
+    readonly returnDoc?: string;
+    readonly finishFunc?: string;
+    readonly shadows?: string;
+    readonly shadowedBy?: string;
+
+    constructor(data: {
+        name: string;
+        cIdentifier: string;
+        returnType: GirType;
+        parameters: GirParameter[];
+        instanceParameter?: GirParameter;
+        throws: boolean;
+        doc?: string;
+        returnDoc?: string;
+        finishFunc?: string;
+        shadows?: string;
+        shadowedBy?: string;
+    }) {
+        this.name = data.name;
+        this.cIdentifier = data.cIdentifier;
+        this.returnType = data.returnType;
+        this.parameters = data.parameters;
+        this.instanceParameter = data.instanceParameter;
+        this.throws = data.throws;
+        this.doc = data.doc;
+        this.returnDoc = data.returnDoc;
+        this.finishFunc = data.finishFunc;
+        this.shadows = data.shadows;
+        this.shadowedBy = data.shadowedBy;
+    }
+
+    /** True if this follows the async/finish pattern. */
+    isAsync(): boolean {
+        return this.name.endsWith("_async") || this.parameters.some((p) => p.scope === "async");
+    }
+
+    /** True if this is a _finish method for an async operation. */
+    isAsyncFinish(): boolean {
+        return this.name.endsWith("_finish");
+    }
+
+    /** Gets the corresponding _finish method name if this is async. */
+    getFinishMethodName(): string | null {
+        if (this.name.endsWith("_async")) {
+            return this.name.replace(/_async$/, "_finish");
+        }
+        return null;
+    }
+
+    /** Gets required (non-optional, non-nullable) input parameters. */
+    getRequiredParameters(): GirParameter[] {
+        return this.parameters.filter((p) => !p.optional && !p.nullable && p.direction === "in");
+    }
+
+    /** Gets optional parameters. */
+    getOptionalParameters(): GirParameter[] {
+        return this.parameters.filter((p) => p.optional || p.nullable);
+    }
+
+    /** True if any parameter is an out parameter. */
+    hasOutParameters(): boolean {
+        return this.parameters.some((p) => p.direction === "out" || p.direction === "inout");
+    }
+
+    /** Gets out parameters only. */
+    getOutParameters(): GirParameter[] {
+        return this.parameters.filter((p) => p.direction === "out" || p.direction === "inout");
+    }
+}
+
+/**
+ * Constructor for a class or record.
+ */
+export class GirConstructor {
+    readonly name: string;
+    readonly cIdentifier: string;
+    readonly returnType: GirType;
+    readonly parameters: GirParameter[];
+    readonly throws: boolean;
+    readonly doc?: string;
+    readonly returnDoc?: string;
+    readonly shadows?: string;
+    readonly shadowedBy?: string;
+
+    constructor(data: {
+        name: string;
+        cIdentifier: string;
+        returnType: GirType;
+        parameters: GirParameter[];
+        throws: boolean;
+        doc?: string;
+        returnDoc?: string;
+        shadows?: string;
+        shadowedBy?: string;
+    }) {
+        this.name = data.name;
+        this.cIdentifier = data.cIdentifier;
+        this.returnType = data.returnType;
+        this.parameters = data.parameters;
+        this.throws = data.throws;
+        this.doc = data.doc;
+        this.returnDoc = data.returnDoc;
+        this.shadows = data.shadows;
+        this.shadowedBy = data.shadowedBy;
+    }
+
+    /** Gets required (non-optional, non-nullable) input parameters. */
+    getRequiredParameters(): GirParameter[] {
+        return this.parameters.filter((p) => !p.optional && !p.nullable && p.direction === "in");
+    }
+}
+
+/**
+ * Standalone function or static method.
+ */
+export class GirFunction {
+    readonly name: string;
+    readonly cIdentifier: string;
+    readonly returnType: GirType;
+    readonly parameters: GirParameter[];
+    readonly throws: boolean;
+    readonly doc?: string;
+    readonly returnDoc?: string;
+    readonly shadows?: string;
+    readonly shadowedBy?: string;
+
+    constructor(data: {
+        name: string;
+        cIdentifier: string;
+        returnType: GirType;
+        parameters: GirParameter[];
+        throws: boolean;
+        doc?: string;
+        returnDoc?: string;
+        shadows?: string;
+        shadowedBy?: string;
+    }) {
+        this.name = data.name;
+        this.cIdentifier = data.cIdentifier;
+        this.returnType = data.returnType;
+        this.parameters = data.parameters;
+        this.throws = data.throws;
+        this.doc = data.doc;
+        this.returnDoc = data.returnDoc;
+        this.shadows = data.shadows;
+        this.shadowedBy = data.shadowedBy;
+    }
+
+    /** True if this follows the async/finish pattern. */
+    isAsync(): boolean {
+        return this.name.endsWith("_async") || this.parameters.some((p) => p.scope === "async");
+    }
+
+    /** Gets required (non-optional, non-nullable) input parameters. */
+    getRequiredParameters(): GirParameter[] {
+        return this.parameters.filter((p) => !p.optional && !p.nullable && p.direction === "in");
+    }
+}

package/src/model/callback.ts

@@ -0,0 +1,30 @@
+import type { GirParameter } from "./parameter.js";
+import type { GirType } from "./type.js";
+
+/**
+ * Callback type definition (function pointer type).
+ */
+export class GirCallback {
+    readonly name: string;
+    readonly qualifiedName: string;
+    readonly cType: string;
+    readonly returnType: GirType;
+    readonly parameters: GirParameter[];
+    readonly doc?: string;
+
+    constructor(data: {
+        name: string;
+        qualifiedName: string;
+        cType: string;
+        returnType: GirType;
+        parameters: GirParameter[];
+        doc?: string;
+    }) {
+        this.name = data.name;
+        this.qualifiedName = data.qualifiedName;
+        this.cType = data.cType;
+        this.returnType = data.returnType;
+        this.parameters = data.parameters;
+        this.doc = data.doc;
+    }
+}