@ts-for-gir/lib 4.0.0-rc.5 → 4.0.0-rc.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ts-for-gir/lib",
-  "version": "4.0.0-rc.5",
+  "version": "4.0.0-rc.7",
   "description": "Typescript .d.ts generator from GIR for gjs",
   "main": "src/index.ts",
   "module": "src/index.ts",
@@ -41,7 +41,7 @@
     "type definitions"
   ],
   "devDependencies": {
-    "@ts-for-gir/tsconfig": "^4.0.0-rc.5",
+    "@ts-for-gir/tsconfig": "^4.0.0-rc.7",
     "@types/ejs": "^3.1.5",
     "@types/lodash": "^4.17.24",
     "@types/node": "^25.6.0",
@@ -49,9 +49,9 @@
     "typescript": "^6.0.3"
   },
   "dependencies": {
-    "@gi.ts/parser": "^4.0.0-rc.5",
-    "@ts-for-gir/reporter": "^4.0.0-rc.5",
-    "@ts-for-gir/templates": "^4.0.0-rc.5",
+    "@gi.ts/parser": "^4.0.0-rc.7",
+    "@ts-for-gir/reporter": "^4.0.0-rc.7",
+    "@ts-for-gir/templates": "^4.0.0-rc.7",
     "colorette": "^2.0.20",
     "ejs": "^5.0.2",
     "glob": "^13.0.6",

package/src/dependency-manager.ts

@@ -132,6 +132,15 @@ export class DependencyManager {
 	}
 
 	createImportPath(packageName: string, namespace: string, version: string): string {
+		// In external-deps mode every dep import is resolved against an installed npm package
+		// (e.g. `@girs/glib-2.0`), regardless of `package` mode. User-supplied overrides win
+		// for namespaces with non-default scopes/versions (e.g. `Soup → @girs/soup-3.0`).
+		if (this.config.externalDeps) {
+			const override = this.config.externalPackages?.[namespace];
+			if (override) return override;
+			const importName = transformImportName(packageName);
+			return `${this.config.npmScope}/${importName}`;
+		}
 		if (!this.config.package) {
 			return `gi://${namespace}?version=${version}`;
 		}

package/src/gir/function.ts

@@ -248,9 +248,7 @@ export class IntrospectedFunction extends IntrospectedNamespaceMember {
 					const { type, isOptional } = p;
 
 					if (allowOptions) {
-						if (type instanceof NullableType) {
-							params.push(p.copy({ isOptional: true }));
-						} else if (!isOptional) {
+						if (!isOptional) {
 							params.push(p);
 							return { allowOptions: false, params };
 						} else {

package/src/gir/introspected-classes.ts

@@ -5,6 +5,7 @@ import {
 	Generic,
 	GenericType,
 	GenerifiedTypeIdentifier,
+	NullableType,
 	type TypeExpression,
 	TypeIdentifier,
 	UnknownType,
@@ -47,6 +48,40 @@ import { IntrospectedSignal } from "./signal.ts";
 
 const log = new ConsoleReporter(true, "gir/introspected-classes", true);
 
+/**
+ * Walks the implementing class's `extends` chain (skipping the prerequisite class
+ * itself) and reports whether any ancestor *shadows* a member by declaring its
+ * own member of the given name. A shadow indicates the parent chain has
+ * overridden the prerequisite's member with a possibly incompatible type, which
+ * would otherwise leave the implementing class unable to satisfy the
+ * interface's contract.
+ */
+function hasExtendsShadowOf(cls: IntrospectedBaseClass, prerequisite: IntrospectedBaseClass, name: string): boolean {
+	let current = cls.resolveParents().extends();
+	while (current) {
+		const node = current.node;
+		if (node !== prerequisite) {
+			const hasOwn = [...node.props, ...node.fields, ...node.members].some((m) => m.name === name);
+			if (hasOwn) return true;
+		}
+		current = current.extends();
+	}
+	return false;
+}
+
+function resolveNullableProperties(cls: IntrospectedBaseClass): void {
+	for (const prop of cls.props) {
+		if (prop.type instanceof NullableType) continue;
+
+		const getterName = prop.getter ?? `get_${prop.name}`;
+		const getter = cls.members.find((m) => m.name === getterName && !(m instanceof IntrospectedStaticClassFunction));
+
+		if (getter instanceof IntrospectedClassFunction && getter.return() instanceof NullableType) {
+			prop.type = new NullableType(prop.type);
+		}
+	}
+}
+
 /**
  * Represents a signal with metadata
  */
@@ -75,6 +110,8 @@ export class IntrospectedClassFunction<
 	returnTypeDoc?: string | null;
 	/** If this function was generated from a signal, stores the signal name. */
 	signalOrigin?: string;
+	/** GIR glib:finish-func attribute: name of the function that finishes this async operation. */
+	finishFuncName?: string;
 
 	generics: Generic[] = [];
 
@@ -143,6 +180,7 @@ export class IntrospectedClassFunction<
 
 		fn.generics = [...this.generics];
 		fn.returnTypeDoc = this.returnTypeDoc;
+		fn.finishFuncName = this.finishFuncName;
 
 		if (interfaceParent) {
 			fn.interfaceParent = interfaceParent;
@@ -177,6 +215,10 @@ export class IntrospectedClassFunction<
 		// Convert the function to a class function
 		const { raw_name: name, output_parameters, parameters, return_type, doc, isIntrospectable } = fn;
 
+		// A function with shadowed-by is superseded by the shadowing function (which uses `shadows`)
+		// and takes the original name. Do not emit the shadowed function to avoid duplicate declarations.
+		const isShadowedBy = element.$["shadowed-by"] != null;
+
 		const classFn = new IntrospectedClassFunction({
 			parent,
 			name,
@@ -184,11 +226,12 @@ export class IntrospectedClassFunction<
 			parameters,
 			return_type,
 			doc,
-			isIntrospectable,
+			isIntrospectable: isIntrospectable && !isShadowedBy,
 		});
 
 		classFn.returnTypeDoc = fn.returnTypeDoc;
 		classFn.generics = [...fn.generics];
+		classFn.finishFuncName = element.$["glib:finish-func"];
 
 		return classFn;
 	}
@@ -396,6 +439,8 @@ export class IntrospectedStaticClassFunction extends IntrospectedClassFunction {
 		// Convert the function to a static class function
 		const { raw_name: name, output_parameters, parameters, return_type, doc, isIntrospectable } = fn;
 
+		const isShadowedBy = m.$["shadowed-by"] != null;
+
 		return new IntrospectedStaticClassFunction({
 			parent,
 			name,
@@ -403,7 +448,7 @@ export class IntrospectedStaticClassFunction extends IntrospectedClassFunction {
 			parameters,
 			return_type,
 			doc,
-			isIntrospectable,
+			isIntrospectable: isIntrospectable && !isShadowedBy,
 		});
 	}
 }
@@ -853,13 +898,19 @@ export class IntrospectedClass extends IntrospectedBaseClass {
 			});
 		}
 
-		// If an interface inherits from a class (such as Gtk.Widget)
-		// we need to pull in every item from that class...
+		// An interface's <prerequisite> of class type is always satisfied by the
+		// implementing class's actual parent chain — those members are already
+		// inherited via TS class inheritance, so we don't re-emit them. The one
+		// case we still need to handle: when the parent chain has a same-named
+		// member with an incompatible signature/type, we re-emit the interface's
+		// version so `filterConflicts` / `filterFunctionConflict` can broaden or
+		// override it to satisfy both `extends` and `implements` simultaneously.
 		for (const implemented of resolution.implements()) {
 			const extended = implemented.extends();
 			if (extended?.node instanceof IntrospectedClass) {
 				for (const item of getItems(extended.node)) {
 					if (items.has(item.name) || !validate(item)) continue;
+					if (!hasExtendsShadowOf(this, extended.node, item.name)) continue;
 					items.set(item.name, item);
 				}
 			}
@@ -1036,6 +1087,7 @@ export class IntrospectedClass extends IntrospectedBaseClass {
 		IntrospectedClass.parseBasicProperties(element, clazz, ns, options);
 		IntrospectedClass.parseResolveNames(element, clazz, ns, name);
 		IntrospectedClass.parseInheritanceAndMembers(element, clazz, ns, options);
+		resolveNullableProperties(clazz);
 
 		return clazz;
 	}
@@ -1342,6 +1394,7 @@ export class IntrospectedInterface extends IntrospectedBaseClass {
 		IntrospectedInterface.parseInterfaceBasicProperties(element, iface, namespace, options);
 		IntrospectedInterface.parseInterfaceResolveNames(element, iface, namespace, name);
 		IntrospectedInterface.parseInterfaceMembers(element, iface, namespace, options);
+		resolveNullableProperties(iface);
 
 		return iface;
 	}

package/src/gir/promisify.ts

@@ -62,6 +62,11 @@ function findFinishMethodInClass(cls: IntrospectedBaseClass, node: IntrospectedC
 			? [...cls.constructors, ...cls.members.filter((m) => m instanceof IntrospectedStaticClassFunction)]
 			: [...cls.members.filter((m) => !(m instanceof IntrospectedStaticClassFunction))];
 
+	// Prefer the GIR-specified finish function name over name heuristics
+	if (node.finishFuncName) {
+		return members.find((m) => m.name === node.finishFuncName);
+	}
+
 	return members.find(
 		(m) => m.name === `${node.name.replace(/_async$/, "")}_finish` || m.name === `${node.name}_finish`,
 	);

package/src/gir/property.ts

@@ -1,5 +1,5 @@
 import type { FormatGenerator } from "../generators/generator.ts";
-import type { TypeExpression } from "../gir.ts";
+import { NullableType, type TypeExpression } from "../gir.ts";
 import type { GirFieldElement, GirPropertyElement } from "../index.ts";
 import type { OptionsLoad } from "../types/index.ts";
 import type { Options } from "../types/introspected.ts";
@@ -98,6 +98,10 @@ export class IntrospectedProperty extends IntrospectedBase<IntrospectedEnum | In
 	readonly writable: boolean = false;
 	readonly readable: boolean = true;
 	readonly constructOnly: boolean;
+	/** GIR default-value attribute: the default value of the property as a string. */
+	defaultValue?: string;
+	/** GIR getter attribute: name of the getter method for this property (used for nullable inference). */
+	getter?: string;
 
 	get namespace() {
 		return this.parent.namespace;
@@ -110,7 +114,7 @@ export class IntrospectedProperty extends IntrospectedBase<IntrospectedEnum | In
 	}): IntrospectedProperty {
 		const { name, writable, readable, type, constructOnly, parent } = this;
 
-		return new IntrospectedProperty({
+		const prop = new IntrospectedProperty({
 			name: options?.name ?? name,
 			writable,
 			readable,
@@ -118,6 +122,9 @@ export class IntrospectedProperty extends IntrospectedBase<IntrospectedEnum | In
 			constructOnly,
 			parent: options?.parent ?? parent,
 		})._copyBaseProperties(this);
+		prop.defaultValue = this.defaultValue;
+		prop.getter = this.getter;
+		return prop;
 	}
 
 	accept(visitor: GirVisitor): IntrospectedProperty {
@@ -198,6 +205,14 @@ export class IntrospectedProperty extends IntrospectedBase<IntrospectedEnum | In
 			property.metadata = parseMetadata(element);
 		}
 
+		property.defaultValue = element.$["default-value"];
+
+		property.getter = element.$.getter;
+
+		if (element.$.nullable === "1" || element.$["allow-none"] === "1") {
+			property.type = new NullableType(property.type);
+		}
+
 		return property;
 	}
 }

package/src/gir/registry.ts

@@ -103,13 +103,17 @@ export class NSRegistry {
 	}
 
 	transform(options: OptionsTransform) {
-		const GLib = this.assertNamespace("GLib", "2.0");
-		const Gio = this.assertNamespace("Gio", "2.0");
-		const GObject = this.assertNamespace("GObject", "2.0");
+		// In tolerant external-deps mode (with --allow-missing-deps) the core namespaces
+		// may not be loaded. Sync their package_version only when actually present;
+		// generify/inject still run on whatever IS loaded (other modules' transformations
+		// don't depend on GLib being in the registry).
+		const GLib = this.namespace("GLib", "2.0");
+		const Gio = this.namespace("Gio", "2.0");
+		const GObject = this.namespace("GObject", "2.0");
 
 		// These follow the GLib version.
-		Gio.package_version = [...GLib.package_version];
-		GObject.package_version = [...GLib.package_version];
+		if (GLib && Gio) Gio.package_version = [...GLib.package_version];
+		if (GLib && GObject) GObject.package_version = [...GLib.package_version];
 
 		const interfaceVisitor = new InterfaceVisitor();
 
@@ -119,11 +123,13 @@ export class NSRegistry {
 
 		this.registerTransformation(classVisitor);
 
-		console.log("Adding generics...");
-		generify(this, options.inferGenerics);
+		if (GLib && Gio) {
+			console.log("Adding generics...");
+			generify(this, options.inferGenerics);
 
-		console.log("Injecting types...");
-		inject(this);
+			console.log("Injecting types...");
+			inject(this);
+		}
 	}
 
 	defaultVersionOf(name: string): string | null {

package/src/types/options-generation.ts

@@ -64,4 +64,25 @@ export interface OptionsGeneration extends OptionsBase {
 	merge?: boolean;
 	/** Directory containing pre-generated TypeDoc JSON files for merge mode (from 'ts-for-gir json') */
 	jsonDir?: string;
+	/**
+	 * External-deps mode: emit `import` statements that reference dependency types from
+	 * already-installed npm packages (e.g. `@girs/glib-2.0`) instead of regenerating them.
+	 * Designed for project-local GIRs (Vala bridges etc.) where the surrounding `@girs/*`
+	 * ecosystem is already in node_modules. No GJS supporting files, no index aggregator.
+	 */
+	externalDeps: boolean;
+	/**
+	 * In `externalDeps` mode, allow generation to proceed even when some transitive dep GIRs
+	 * cannot be found. Default is strict: missing deps abort the run, since divergent dep
+	 * availability between environments (dev with -devel packages vs CI without) would
+	 * silently produce inconsistent generated `.d.ts` output.
+	 */
+	allowMissingDeps: boolean;
+	/**
+	 * Override the default `<npmScope>/<importName>` mapping for individual namespaces when
+	 * resolving external dependency imports in `externalDeps` mode.
+	 *
+	 * Example: `{ Soup: '@girs/soup-3.0', GLib: '@girs/glib-2.0' }`
+	 */
+	externalPackages?: Record<string, string>;
 }

package/src/types/user-config.ts

@@ -77,4 +77,24 @@ export interface UserConfig {
 	merge?: boolean;
 	/** Directory containing pre-generated TypeDoc JSON files for merge mode (from 'ts-for-gir json') */
 	jsonDir?: string;
+	/**
+	 * External-deps mode: emit `import` statements that reference dependency types from
+	 * already-installed npm packages (e.g. `@girs/glib-2.0`) instead of regenerating them.
+	 * Designed for project-local GIRs (Vala bridges etc.) where the surrounding `@girs/*`
+	 * ecosystem is already in node_modules.
+	 */
+	externalDeps: boolean;
+	/**
+	 * Allow `externalDeps` generation to proceed when some transitive dep GIRs are missing.
+	 * Default is strict: missing deps cause an error to prevent silent type-quality drift
+	 * between environments with and without system GIR -devel packages installed.
+	 */
+	allowMissingDeps: boolean;
+	/**
+	 * Override the default `<npmScope>/<importName>` mapping for individual namespaces when
+	 * resolving external dependency imports in `externalDeps` mode.
+	 *
+	 * Example: `{ Soup: '@girs/soup-3.0', GLib: '@girs/glib-2.0' }`
+	 */
+	externalPackages?: Record<string, string>;
 }

package/src/utils/conflicts.ts

@@ -261,8 +261,13 @@ function checkFunctionConflicts<T extends IntrospectedClassFunction | Introspect
 		});
 	});
 
-	// Check field/property conflicts
-	const hasFieldConflicts = checkFieldPropertyConflicts(base, functionElement.name);
+	// Static methods can coexist with instance fields/properties of the same name
+	// in TypeScript (e.g. `static map(...)` alongside `map: T[]`), so skip the check
+	// for them. The conflict only applies to instance methods.
+	const hasFieldConflicts =
+		functionElement instanceof IntrospectedStaticClassFunction
+			? false
+			: checkFieldPropertyConflicts(base, functionElement.name);
 
 	// Check GObject reserved methods
 	const hasGObjectConflicts = checkGObjectConflicts(base, functionElement.name);

package/src/utils/gir-defaults.ts

@@ -0,0 +1,66 @@
+import type { GirModule } from "../gir-module.ts";
+
+/**
+ * Resolves a single C enum/bitfield constant to its GJS-qualified path by searching
+ * the module's own enum_constants map and then all direct and transitive dependencies.
+ * Returns [namespaceName, enumTypeName, memberName] or null if not found.
+ *
+ * Called during the generation phase (after all modules have been parsed), so all
+ * dependency enum_constants maps are fully populated. Each GirModule.enum_constants
+ * is an O(1) Map; the total cost per call is O(deps) — negligible given the small
+ * fraction of properties that carry a default-value attribute.
+ */
+function resolveCEnumConstant(cIdentifier: string, ns: GirModule): readonly [string, string, string] | null {
+	// Check own namespace first
+	const own = ns.enum_constants.get(cIdentifier);
+	if (own) return [ns.namespace, own[0], own[1]] as const;
+
+	// Check all direct and transitive dependencies
+	for (const dep of ns.allDependencies) {
+		const depModule = ns.getInstalledImport(dep.namespace);
+		if (!depModule) continue;
+		const entry = depModule.enum_constants.get(cIdentifier);
+		if (entry) return [depModule.namespace, entry[0], entry[1]] as const;
+	}
+
+	return null;
+}
+
+function convertSingleCValue(value: string, ns: GirModule): string {
+	const trimmed = value.trim();
+
+	if (trimmed === "NULL") return "null";
+	if (trimmed === "TRUE") return "true";
+	if (trimmed === "FALSE") return "false";
+
+	// Normalize C floats: "0.000000" → "0", "1.500000" → "1.5"
+	if (/^-?\d+\.\d+$/.test(trimmed)) {
+		const n = parseFloat(trimmed);
+		if (!Number.isNaN(n)) return String(n);
+	}
+
+	// Resolve C enum/bitfield constant (own namespace + all dependencies)
+	// e.g. "GTK_ALIGN_FILL"         → "Gtk.Align.FILL"
+	// e.g. "GDK_NO_MODIFIER_MASK"   → "Gdk.ModifierType.NO_MODIFIER_MASK"
+	// e.g. "PANGO_ALIGN_LEFT"       → "Pango.Alignment.LEFT"
+	const entry = resolveCEnumConstant(trimmed, ns);
+	if (entry) return `${entry[0]}.${entry[1]}.${entry[2]}`;
+
+	return trimmed;
+}
+
+/**
+ * Converts a raw C default-value string from GIR XML to its JavaScript equivalent.
+ * Handles NULL/TRUE/FALSE, C float literals, C enum/bitfield constants (including
+ * cross-namespace lookups), and bitmask combinations (A | B | C).
+ */
+export function convertCDefaultValue(rawValue: string, ns: GirModule): string {
+	// Handle bitmask combinations: "A | B | C"
+	if (rawValue.includes("|")) {
+		return rawValue
+			.split("|")
+			.map((part) => convertSingleCValue(part, ns))
+			.join(" | ");
+	}
+	return convertSingleCValue(rawValue, ns);
+}

package/src/utils/index.ts

@@ -2,6 +2,7 @@ export * from "./conflicts.ts";
 export * from "./documentation.ts";
 export * from "./files.ts";
 export * from "./generation.ts";
+export * from "./gir-defaults.ts";
 export * from "./gir-parsing.ts";
 export * from "./girs.ts";
 export * from "./naming.ts";

package/src/validators/class.ts

@@ -3,7 +3,7 @@ import { IntrospectedError } from "../gir/error.ts";
 import type { IntrospectedBaseClass, IntrospectedClass, IntrospectedInterface } from "../gir/introspected-classes.ts";
 import { IntrospectedClassFunction, IntrospectedStaticClassFunction } from "../gir/introspected-classes.ts";
 import { IntrospectedRecord } from "../gir/record.ts";
-import { AnyType, NativeType, TypeIdentifier } from "../gir.ts";
+import { AnyType, ArrayType, NativeType, TypeIdentifier } from "../gir.ts";
 import { resolveTypeIdentifier } from "../utils/type-resolution.ts";
 import { GirVisitor } from "../visitor.ts";
 
@@ -125,9 +125,10 @@ const fixMissingParent = <T extends IntrospectedBaseClass>(node: T): T => {
 };
 
 /**
- * Fields cannot be array types, error types,
- * or class-like types in GJS. This strips
- * fields which have these "complex" types.
+ * Removes fields with types that GJS cannot directly expose on a struct instance.
+ * Error types and non-simple non-pointer struct fields are removed.
+ * Array fields (zero-terminated pointer arrays, T**) are always safe in GJS and are only
+ * rejected if the element type is private or disguised.
  *
  * @param node
  */
@@ -135,6 +136,17 @@ const removeComplexFields = <T extends IntrospectedBaseClass>(node: T): T => {
 	const { namespace } = node;
 
 	node.fields = node.fields.filter((f) => {
+		// Array fields (T**) are marshalled by GJS for any GBoxed element type.
+		// Only reject arrays of private/disguised element types.
+		if (f.type instanceof ArrayType) {
+			const elementType = f.type.deepUnwrap();
+			if (elementType instanceof TypeIdentifier) {
+				const classNode = resolveTypeIdentifier(namespace, elementType);
+				return !classNode?.isPrivate;
+			}
+			return true;
+		}
+
 		const type = f.type.deepUnwrap();
 
 		if (type instanceof NativeType) {