@gtkx/gir 0.19.0 → 0.21.0

package/src/model/class.ts

@@ -0,0 +1,215 @@
+import type { GirConstructor, GirFunction, GirMethod } from "./callables.js";
+import type { GirProperty } from "./property.js";
+import type { RepositoryLike } from "./repository-like.js";
+import type { GirSignal } from "./signal.js";
+
+/**
+ * GObject class with helper methods for type graph traversal.
+ *
+ * Receives a repository reference at construction time to enable
+ * inheritance chain traversal and interface resolution.
+ */
+export class GirClass {
+    readonly name: string;
+    readonly qualifiedName: string;
+    readonly cType: string;
+    readonly parent: string | null;
+    readonly abstract: boolean;
+    readonly glibTypeName?: string;
+    readonly glibGetType?: string;
+    readonly cSymbolPrefix?: string;
+    readonly fundamental: boolean;
+    readonly refFunc?: string;
+    readonly unrefFunc?: string;
+    readonly implements: string[];
+    readonly methods: GirMethod[];
+    readonly constructors: GirConstructor[];
+    readonly staticFunctions: GirFunction[];
+    readonly properties: GirProperty[];
+    readonly signals: GirSignal[];
+    readonly doc?: string;
+
+    private readonly repo: RepositoryLike;
+
+    constructor(
+        data: {
+            name: string;
+            qualifiedName: string;
+            cType: string;
+            parent: string | null;
+            abstract: boolean;
+            glibTypeName?: string;
+            glibGetType?: string;
+            cSymbolPrefix?: string;
+            fundamental?: boolean;
+            refFunc?: string;
+            unrefFunc?: string;
+            implements: string[];
+            methods: GirMethod[];
+            constructors: GirConstructor[];
+            staticFunctions: GirFunction[];
+            properties: GirProperty[];
+            signals: GirSignal[];
+            doc?: string;
+        },
+        repo: RepositoryLike,
+    ) {
+        this.name = data.name;
+        this.qualifiedName = data.qualifiedName;
+        this.cType = data.cType;
+        this.parent = data.parent;
+        this.abstract = data.abstract;
+        this.glibTypeName = data.glibTypeName;
+        this.glibGetType = data.glibGetType;
+        this.cSymbolPrefix = data.cSymbolPrefix;
+        this.fundamental = data.fundamental ?? false;
+        this.refFunc = data.refFunc;
+        this.unrefFunc = data.unrefFunc;
+        this.implements = data.implements;
+        this.methods = data.methods;
+        this.constructors = data.constructors;
+        this.staticFunctions = data.staticFunctions;
+        this.properties = data.properties;
+        this.signals = data.signals;
+        this.doc = data.doc;
+        this.repo = repo;
+    }
+
+    /** Checks if this class is a subclass of another (direct or transitive). */
+    isSubclassOf(qualifiedName: string): boolean {
+        if (this.qualifiedName === qualifiedName) return true;
+        if (!this.parent) return false;
+        if (this.parent === qualifiedName) return true;
+        const parentClass = this.repo.resolveClass(this.parent);
+        return parentClass?.isSubclassOf(qualifiedName) ?? false;
+    }
+
+    /** Gets the full inheritance chain from this class to the root. */
+    getInheritanceChain(): string[] {
+        const chain: string[] = [this.qualifiedName];
+        let current: GirClass | null = this as GirClass;
+        while (current?.parent) {
+            chain.push(current.parent);
+            current = this.repo.resolveClass(current.parent);
+        }
+        return chain;
+    }
+
+    /** Gets the parent class object, or null if this is a root class. */
+    getParent(): GirClass | null {
+        return this.parent ? this.repo.resolveClass(this.parent) : null;
+    }
+
+    /** Checks if this class directly or transitively implements an interface. */
+    implementsInterface(qualifiedName: string): boolean {
+        if (this.implements.includes(qualifiedName)) return true;
+        const parent = this.getParent();
+        return parent?.implementsInterface(qualifiedName) ?? false;
+    }
+
+    /** Gets all implemented interfaces including inherited ones. */
+    getAllImplementedInterfaces(): string[] {
+        const interfaces = new Set<string>(this.implements);
+        let current = this.getParent();
+        while (current) {
+            for (const iface of current.implements) {
+                interfaces.add(iface);
+            }
+            current = current.getParent();
+        }
+        return [...interfaces];
+    }
+
+    /** Finds a method defined on this class by name. */
+    getMethod(name: string): GirMethod | null {
+        return this.methods.find((m) => m.name === name) ?? null;
+    }
+
+    /** Finds a property defined on this class by name. */
+    getProperty(name: string): GirProperty | null {
+        return this.properties.find((p) => p.name === name) ?? null;
+    }
+
+    /** Finds a signal defined on this class by name. */
+    getSignal(name: string): GirSignal | null {
+        return this.signals.find((s) => s.name === name) ?? null;
+    }
+
+    /** Finds a constructor by name. */
+    getConstructor(name: string): GirConstructor | null {
+        return this.constructors.find((c) => c.name === name) ?? null;
+    }
+
+    /** Gets all methods including inherited ones. */
+    getAllMethods(): GirMethod[] {
+        const methods = [...this.methods];
+        let current = this.getParent();
+        while (current) {
+            methods.push(...current.methods);
+            current = current.getParent();
+        }
+        return methods;
+    }
+
+    /** Gets all properties including inherited ones. */
+    getAllProperties(): GirProperty[] {
+        const properties = [...this.properties];
+        let current = this.getParent();
+        while (current) {
+            properties.push(...current.properties);
+            current = current.getParent();
+        }
+        return properties;
+    }
+
+    /** Gets all signals including inherited ones. */
+    getAllSignals(): GirSignal[] {
+        const signals = [...this.signals];
+        let current = this.getParent();
+        while (current) {
+            signals.push(...current.signals);
+            current = current.getParent();
+        }
+        return signals;
+    }
+
+    /** Finds a method by name, searching up the inheritance chain. */
+    findMethod(name: string): GirMethod | null {
+        return this.getMethod(name) ?? this.getParent()?.findMethod(name) ?? null;
+    }
+
+    /** Finds a method by its C identifier. */
+    getMethodByCIdentifier(cIdentifier: string): GirMethod | null {
+        return this.methods.find((m) => m.cIdentifier === cIdentifier) ?? null;
+    }
+
+    /** Finds a property by name, searching up the inheritance chain. */
+    findProperty(name: string): GirProperty | null {
+        return this.getProperty(name) ?? this.getParent()?.findProperty(name) ?? null;
+    }
+
+    /** Finds a signal by name, searching up the inheritance chain. */
+    findSignal(name: string): GirSignal | null {
+        return this.getSignal(name) ?? this.getParent()?.findSignal(name) ?? null;
+    }
+
+    /** True if this is an abstract class. */
+    isAbstract(): boolean {
+        return this.abstract;
+    }
+
+    /** True if this has a GType (most GObject classes do). */
+    hasGType(): boolean {
+        return this.glibTypeName !== undefined;
+    }
+
+    /** True if this is a fundamental type with custom ref/unref functions. */
+    isFundamental(): boolean {
+        return this.fundamental && this.refFunc !== undefined && this.unrefFunc !== undefined;
+    }
+
+    /** Gets direct subclasses of this class. */
+    getDirectSubclasses(): GirClass[] {
+        return this.repo.findClasses((cls) => cls.parent === this.qualifiedName);
+    }
+}

package/src/model/constant.ts

@@ -0,0 +1,29 @@
+import type { GirType } from "./type.js";
+
+/**
+ * Constant value defined in a GIR namespace.
+ */
+export class GirConstant {
+    readonly name: string;
+    readonly qualifiedName: string;
+    readonly cType: string;
+    readonly value: string;
+    readonly type: GirType;
+    readonly doc?: string;
+
+    constructor(data: {
+        name: string;
+        qualifiedName: string;
+        cType: string;
+        value: string;
+        type: GirType;
+        doc?: string;
+    }) {
+        this.name = data.name;
+        this.qualifiedName = data.qualifiedName;
+        this.cType = data.cType;
+        this.value = data.value;
+        this.type = data.type;
+        this.doc = data.doc;
+    }
+}

package/src/model/enumeration.ts

@@ -0,0 +1,64 @@
+/**
+ * Enumeration member.
+ */
+export class GirEnumerationMember {
+    readonly name: string;
+    readonly value: string;
+    readonly cIdentifier: string;
+    readonly doc?: string;
+
+    constructor(data: {
+        name: string;
+        value: string;
+        cIdentifier: string;
+        doc?: string;
+    }) {
+        this.name = data.name;
+        this.value = data.value;
+        this.cIdentifier = data.cIdentifier;
+        this.doc = data.doc;
+    }
+}
+
+/**
+ * Enumeration or bitfield with helper methods.
+ */
+export class GirEnumeration {
+    readonly name: string;
+    readonly qualifiedName: string;
+    readonly cType: string;
+    readonly members: GirEnumerationMember[];
+    readonly glibGetType?: string;
+    readonly doc?: string;
+
+    constructor(data: {
+        name: string;
+        qualifiedName: string;
+        cType: string;
+        members: GirEnumerationMember[];
+        glibGetType?: string;
+        doc?: string;
+    }) {
+        this.name = data.name;
+        this.qualifiedName = data.qualifiedName;
+        this.cType = data.cType;
+        this.members = data.members;
+        this.glibGetType = data.glibGetType;
+        this.doc = data.doc;
+    }
+
+    /** Finds a member by name. */
+    getMember(name: string): GirEnumerationMember | null {
+        return this.members.find((m) => m.name === name) ?? null;
+    }
+
+    /** Finds a member by value. */
+    getMemberByValue(value: string): GirEnumerationMember | null {
+        return this.members.find((m) => m.value === value) ?? null;
+    }
+
+    /** Gets all member names. */
+    getMemberNames(): string[] {
+        return this.members.map((m) => m.name);
+    }
+}

package/src/model/field.ts

@@ -0,0 +1,29 @@
+import type { GirType } from "./type.js";
+
+/**
+ * Field within a record or class.
+ */
+export class GirField {
+    readonly name: string;
+    readonly type: GirType;
+    readonly writable: boolean;
+    readonly readable: boolean;
+    readonly private: boolean;
+    readonly doc?: string;
+
+    constructor(data: {
+        name: string;
+        type: GirType;
+        writable: boolean;
+        readable: boolean;
+        private: boolean;
+        doc?: string;
+    }) {
+        this.name = data.name;
+        this.type = data.type;
+        this.writable = data.writable;
+        this.readable = data.readable;
+        this.private = data.private;
+        this.doc = data.doc;
+    }
+}

package/src/model/interface.ts

@@ -0,0 +1,89 @@
+import type { GirMethod } from "./callables.js";
+import type { GirProperty } from "./property.js";
+import type { RepositoryLike } from "./repository-like.js";
+import type { GirSignal } from "./signal.js";
+
+/**
+ * GObject interface with helper methods.
+ *
+ * Receives a repository reference at construction time to enable
+ * prerequisite traversal across the type graph.
+ */
+export class GirInterface {
+    readonly name: string;
+    readonly qualifiedName: string;
+    readonly cType: string;
+    readonly glibTypeName?: string;
+    readonly prerequisites: string[];
+    readonly methods: GirMethod[];
+    readonly properties: GirProperty[];
+    readonly signals: GirSignal[];
+    readonly doc?: string;
+
+    private readonly repo: RepositoryLike;
+
+    constructor(
+        data: {
+            name: string;
+            qualifiedName: string;
+            cType: string;
+            glibTypeName?: string;
+            prerequisites: string[];
+            methods: GirMethod[];
+            properties: GirProperty[];
+            signals: GirSignal[];
+            doc?: string;
+        },
+        repo: RepositoryLike,
+    ) {
+        this.name = data.name;
+        this.qualifiedName = data.qualifiedName;
+        this.cType = data.cType;
+        this.glibTypeName = data.glibTypeName;
+        this.prerequisites = data.prerequisites;
+        this.methods = data.methods;
+        this.properties = data.properties;
+        this.signals = data.signals;
+        this.doc = data.doc;
+        this.repo = repo;
+    }
+
+    /** Checks if this interface has a prerequisite (direct or transitive). */
+    hasPrerequisite(qualifiedName: string): boolean {
+        if (this.prerequisites.includes(qualifiedName)) return true;
+        for (const prereq of this.prerequisites) {
+            const prereqIface = this.repo.resolveInterface(prereq);
+            if (prereqIface?.hasPrerequisite(qualifiedName)) return true;
+        }
+        return false;
+    }
+
+    /** Gets all prerequisites including transitive ones. */
+    getAllPrerequisites(): string[] {
+        const all = new Set<string>(this.prerequisites);
+        for (const prereq of this.prerequisites) {
+            const prereqIface = this.repo.resolveInterface(prereq);
+            if (prereqIface) {
+                for (const p of prereqIface.getAllPrerequisites()) {
+                    all.add(p);
+                }
+            }
+        }
+        return [...all];
+    }
+
+    /** Finds a method by name. */
+    getMethod(name: string): GirMethod | null {
+        return this.methods.find((m) => m.name === name) ?? null;
+    }
+
+    /** Finds a property by name. */
+    getProperty(name: string): GirProperty | null {
+        return this.properties.find((p) => p.name === name) ?? null;
+    }
+
+    /** Finds a signal by name. */
+    getSignal(name: string): GirSignal | null {
+        return this.signals.find((s) => s.name === name) ?? null;
+    }
+}

package/src/model/namespace.ts

@@ -0,0 +1,60 @@
+import type { GirAlias } from "./alias.js";
+import type { GirFunction } from "./callables.js";
+import type { GirCallback } from "./callback.js";
+import type { GirClass } from "./class.js";
+import type { GirConstant } from "./constant.js";
+import type { GirEnumeration } from "./enumeration.js";
+import type { GirInterface } from "./interface.js";
+import type { GirRecord } from "./record.js";
+
+/**
+ * Namespace containing all resolved types from a single GIR file.
+ */
+export class GirNamespace {
+    readonly name: string;
+    readonly version: string;
+    readonly sharedLibrary: string;
+    readonly cPrefix: string;
+    readonly classes: Map<string, GirClass>;
+    readonly interfaces: Map<string, GirInterface>;
+    readonly records: Map<string, GirRecord>;
+    readonly enumerations: Map<string, GirEnumeration>;
+    readonly bitfields: Map<string, GirEnumeration>;
+    readonly callbacks: Map<string, GirCallback>;
+    readonly functions: Map<string, GirFunction>;
+    readonly constants: Map<string, GirConstant>;
+    readonly aliases: Map<string, GirAlias>;
+    readonly doc?: string;
+
+    constructor(data: {
+        name: string;
+        version: string;
+        sharedLibrary: string;
+        cPrefix: string;
+        classes: Map<string, GirClass>;
+        interfaces: Map<string, GirInterface>;
+        records: Map<string, GirRecord>;
+        enumerations: Map<string, GirEnumeration>;
+        bitfields: Map<string, GirEnumeration>;
+        callbacks: Map<string, GirCallback>;
+        functions: Map<string, GirFunction>;
+        constants: Map<string, GirConstant>;
+        aliases: Map<string, GirAlias>;
+        doc?: string;
+    }) {
+        this.name = data.name;
+        this.version = data.version;
+        this.sharedLibrary = data.sharedLibrary;
+        this.cPrefix = data.cPrefix;
+        this.classes = data.classes;
+        this.interfaces = data.interfaces;
+        this.records = data.records;
+        this.enumerations = data.enumerations;
+        this.bitfields = data.bitfields;
+        this.callbacks = data.callbacks;
+        this.functions = data.functions;
+        this.constants = data.constants;
+        this.aliases = data.aliases;
+        this.doc = data.doc;
+    }
+}

package/src/model/parameter.ts

@@ -0,0 +1,74 @@
+import type { GirType } from "./type.js";
+
+/**
+ * Parameter to a function, method, or callback.
+ */
+export class GirParameter {
+    readonly name: string;
+    readonly type: GirType;
+    readonly direction: "in" | "out" | "inout";
+    readonly callerAllocates: boolean;
+    readonly nullable: boolean;
+    readonly optional: boolean;
+    readonly scope?: "async" | "call" | "notified" | "forever";
+    readonly closure?: number;
+    readonly destroy?: number;
+    readonly transferOwnership?: "none" | "full" | "container";
+    readonly doc?: string;
+
+    constructor(data: {
+        name: string;
+        type: GirType;
+        direction: "in" | "out" | "inout";
+        callerAllocates: boolean;
+        nullable: boolean;
+        optional: boolean;
+        scope?: "async" | "call" | "notified" | "forever";
+        closure?: number;
+        destroy?: number;
+        transferOwnership?: "none" | "full" | "container";
+        doc?: string;
+    }) {
+        this.name = data.name;
+        this.type = data.type;
+        this.direction = data.direction;
+        this.callerAllocates = data.callerAllocates;
+        this.nullable = data.nullable;
+        this.optional = data.optional;
+        this.scope = data.scope;
+        this.closure = data.closure;
+        this.destroy = data.destroy;
+        this.transferOwnership = data.transferOwnership;
+        this.doc = data.doc;
+    }
+
+    /** True if this is an input parameter. */
+    isIn(): boolean {
+        return this.direction === "in";
+    }
+
+    /** True if this is an output parameter. */
+    isOut(): boolean {
+        return this.direction === "out" || this.direction === "inout";
+    }
+
+    /** True if this is a callback parameter (has scope). */
+    isCallback(): boolean {
+        return this.scope !== undefined;
+    }
+
+    /** True if this is the user_data for a callback. */
+    isClosureData(): boolean {
+        return this.closure !== undefined;
+    }
+
+    /** True if this is a destroy notify for a callback. */
+    isDestroyNotify(): boolean {
+        return this.destroy !== undefined;
+    }
+
+    /** True if caller must allocate memory for this out param. */
+    requiresCallerAllocation(): boolean {
+        return this.callerAllocates && this.isOut();
+    }
+}

package/src/model/property.ts

@@ -0,0 +1,97 @@
+import type { GirType } from "./type.js";
+
+/**
+ * Parsed default value from GIR property definitions.
+ */
+export type DefaultValue =
+    | { kind: "null" }
+    | { kind: "boolean"; value: boolean }
+    | { kind: "number"; value: number }
+    | { kind: "string"; value: string }
+    | { kind: "enum"; cIdentifier: string }
+    | { kind: "unknown"; raw: string };
+
+/**
+ * Parses a raw default value string from GIR into a typed DefaultValue.
+ */
+export function parseDefaultValue(raw: string | undefined): DefaultValue | null {
+    if (raw === undefined) return null;
+    if (raw === "NULL") return { kind: "null" };
+    if (raw === "TRUE") return { kind: "boolean", value: true };
+    if (raw === "FALSE") return { kind: "boolean", value: false };
+
+    const num = Number(raw);
+    if (!Number.isNaN(num)) return { kind: "number", value: num };
+
+    if (raw.startsWith('"') && raw.endsWith('"')) {
+        return { kind: "string", value: raw.slice(1, -1) };
+    }
+
+    if (/^[A-Z][A-Z0-9_]*$/.test(raw)) {
+        return { kind: "enum", cIdentifier: raw };
+    }
+
+    return { kind: "unknown", raw };
+}
+
+/**
+ * GObject property with helper methods.
+ */
+export class GirProperty {
+    readonly name: string;
+    readonly type: GirType;
+    readonly readable: boolean;
+    readonly writable: boolean;
+    readonly constructOnly: boolean;
+    readonly defaultValue: DefaultValue | null;
+    readonly getter?: string;
+    readonly setter?: string;
+    readonly doc?: string;
+
+    constructor(data: {
+        name: string;
+        type: GirType;
+        readable: boolean;
+        writable: boolean;
+        constructOnly: boolean;
+        defaultValue: DefaultValue | null;
+        getter?: string;
+        setter?: string;
+        doc?: string;
+    }) {
+        this.name = data.name;
+        this.type = data.type;
+        this.readable = data.readable;
+        this.writable = data.writable;
+        this.constructOnly = data.constructOnly;
+        this.defaultValue = data.defaultValue;
+        this.getter = data.getter;
+        this.setter = data.setter;
+        this.doc = data.doc;
+    }
+
+    /** True if this property has a default value. */
+    get hasDefault(): boolean {
+        return this.defaultValue !== null;
+    }
+
+    /** True if readable but not writable. */
+    isReadOnly(): boolean {
+        return this.readable && !this.writable;
+    }
+
+    /** True if writable but not readable. */
+    isWriteOnly(): boolean {
+        return this.writable && !this.readable;
+    }
+
+    /** True if can only be set during construction. */
+    isConstructOnly(): boolean {
+        return this.constructOnly;
+    }
+
+    /** True if has both getter and setter methods. */
+    hasAccessors(): boolean {
+        return this.getter !== undefined && this.setter !== undefined;
+    }
+}