@ts-for-gir/lib 4.0.0-beta.9 → 4.0.0-rc.10

package/{lib/utils/objects.js → src/utils/objects.ts}

@@ -1,6 +1,7 @@
-/* eslint-disable @typescript-eslint/unbound-method */
-import lodash from 'lodash';
-export { inspect } from 'util';
+import lodash from "lodash";
+
+export { inspect } from "node:util";
+
 /**
  * Performs a deep comparison between two values to determine if they are
  * equivalent.
@@ -27,6 +28,7 @@ export { inspect } from 'util';
  * // => false
  */
 export const isEqual = lodash.isEqual;
+
 /**
  * Creates an array of values by running each element in collection through iteratee. The iteratee is
  * invoked with three arguments: (value, index|key, collection).
@@ -44,6 +46,7 @@ export const isEqual = lodash.isEqual;
  * @return Returns the new mapped array.
  */
 export const map = lodash.map;
+
 /**
  * Iterates over elements of collection, returning the first element predicate returns truthy for.
  * The predicate is invoked with three arguments: (value, index|key, collection).
@@ -54,6 +57,7 @@ export const map = lodash.map;
  * @return Returns the matched element, else undefined.
  */
 export const find = lodash.find;
+
 /**
  * Recursively merges own and inherited enumerable properties of source
  * objects into the destination object, skipping source properties that resolve
@@ -82,6 +86,7 @@ export const find = lodash.find;
  * // => { 'data': [{ 'user': 'barney', 'age': 36 }, { 'user': 'fred', 'age': 40 }] }
  */
 export const merge = lodash.merge;
+
 /**
  * Creates a shallow clone of value.
  *
@@ -94,6 +99,7 @@ export const merge = lodash.merge;
  * @return Returns the cloned value.
  */
 export const clone = lodash.clone;
+
 /**
  * This method is like clone except that it recursively clones value.
  *
@@ -101,22 +107,23 @@ export const clone = lodash.clone;
  * @return Returns the deep cloned value.
  */
 export const cloneDeep = lodash.cloneDeep;
+
 /**
  * Checking whether some variable is iterable
  * @see https://stackoverflow.com/a/32538867
  * @param obj Variable to check for iterable
  * @returns Whether the variable is iterable or not
  */
-export const isIterable = (obj) => {
-    return obj != null && typeof obj[Symbol.iterator] === 'function';
+export const isIterable = (obj: unknown[]): boolean => {
+	return obj != null && typeof obj[Symbol.iterator] === "function";
 };
+
 /**
  * Union (a ∪ b): create a set that contains the elements of both set a and set b.
  * See https://2ality.com/2015/01/es6-set-operations.html#union
  * @param target
  * @param source
  */
-export const union = (target, source) => {
-    return (target = new Set([...target, ...source]));
+export const union = <T>(target: Set<T> | T[], source: Set<T> | T[]): Set<T> => {
+	return new Set<T>([...target, ...source]);
 };
-//# sourceMappingURL=objects.js.map

package/src/utils/path.ts

@@ -0,0 +1,15 @@
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+// Resolves to the root directory of this package in dev mode.
+// Wrapped in try/catch so a bundled consumer that lacks `import.meta.url`
+// support degrades to "" instead of crashing at module load.
+function resolvePackageDir(): string {
+	try {
+		return resolve(dirname(fileURLToPath(import.meta.url)), "../..");
+	} catch {
+		return "";
+	}
+}
+
+export const __dirname = resolvePackageDir();

package/src/utils/registry.ts

@@ -0,0 +1,5 @@
+import { SanitizedIdentifiers } from "./naming.ts";
+
+export function getSanitizedIdentifiers(): ReadonlyMap<string, string> {
+	return SanitizedIdentifiers;
+}

package/src/utils/strings.ts

@@ -0,0 +1,134 @@
+import { isNumeric } from "./numbers.ts";
+
+/**
+ * Removes line breaks and consecutive white spaces from a given string
+ * @param str
+ * @returns
+ */
+export const cleanString = (str: string) => {
+	str = str.replace(/\r?\n|\r/g, " ");
+	str = str.replace(/\s+/g, " ");
+	return str.trim();
+};
+
+/**
+ * Get the first character of a string
+ * @param str The string to get the first character from
+ * @returns The first character
+ */
+export const getFirstChar = (str: string): string => {
+	return str.charAt(0);
+};
+
+/**
+ * Get the last character of a string
+ * @param str The string to get the last character from
+ * @returns The last character
+ */
+export const getLastChar = (str: string): string => {
+	return str.charAt(str.length - 1);
+};
+
+/**
+ * Check if the first character of a string is numeric
+ * @param str The string to check
+ * @returns Whether the first character is numeric or not
+ */
+export const isFirstCharNumeric = (str: string): boolean => {
+	return isNumeric(getFirstChar(str));
+};
+
+/**
+ * Convert a string to camelCase, keeps the first alphabet character as it is.
+ * @param str The string to convert
+ * @returns The converted string
+ */
+export const camelCase = (str: string): string => {
+	return str
+		.replace(/\s(.)|(\s|-|_|\.)(.)/g, (a) => {
+			return a.toUpperCase();
+		})
+		.replace(/(\s|-|_|\.)/g, "");
+};
+
+/**
+ * Convert a string to `lowerCamelCase`
+ * @param str The string to convert
+ * @returns The converted string
+ */
+export const lowerCamelCase = (str: string): string => {
+	str = camelCase(str);
+	str = getFirstChar(str).toLowerCase() + str.slice(1);
+	return str;
+};
+
+/**
+ * Convert a string to `PascalCase`
+ * @param str The string to convert
+ * @returns The converted string
+ */
+export const pascalCase = (str: string): string => {
+	str = camelCase(str);
+	str = getFirstChar(str).toUpperCase() + str.slice(1);
+	return str;
+};
+
+/** Alias for {@link pascalCase} */
+export const upperCamelCase = pascalCase;
+
+/**
+ * Convert a string to `snake_case`
+ * @param str The string to convert
+ * @returns The converted string
+ */
+export const snakeCase = (str: string): string => {
+	return str
+		.replace(/([a-z])([A-Z])/g, "$1-$2") // replace camelCase with hyphen-case
+		.replace(/[^a-zA-Z0-9-]+/g, "_") // replace non-alphanumeric characters with underscore
+		.replace(/^_+|_+$/g, "") // remove any leading or trailing underscores
+		.toLowerCase();
+};
+
+/**
+ * Convert a string to `kebab-case`
+ * @param str The string to convert
+ * @returns The converted string
+ */
+export const kebabCase = (str: string): string => {
+	return str
+		.replace(/([a-z])([A-Z])/g, "$1-$2") // replace camelCase with hyphen-case
+		.replace(/[^a-zA-Z0-9-]+/g, "-") // replace non-alphanumeric characters with hyphen
+		.replace(/^-+|-+$/g, "") // remove any leading or trailing hyphens
+		.toLowerCase();
+};
+
+/** Alias for {@link kebabCase} */
+export const slugCase = kebabCase;
+
+export const underscores = (str: string): string => {
+	return str.replace(/-|_/g, "_");
+};
+
+/**
+ * Add indents to a string
+ * @param indents The number of indents
+ * @param spaceForIndent The number of spaces for each indent
+ * @returns The indented string
+ */
+export const generateIndent = (indents = 1, spaceForIndent = 4): string => {
+	return " ".repeat(indents * spaceForIndent);
+};
+
+/**
+ * Merge a large array of strings by using a smaller chunk size
+ * @param target The target array to merge into
+ * @param source The source array to merge from
+ * @param chunkSize The size of the chunks to merge
+ * @returns The merged array
+ */
+export const mergeLargeStringArray = (target: string[], source: string[], chunkSize: number = 1000): string[] => {
+	for (let i = 0; i < source.length; i += chunkSize) {
+		target.push(...source.slice(i, i + chunkSize));
+	}
+	return target;
+};

package/src/utils/type-resolution.ts

@@ -0,0 +1,116 @@
+import type { IntrospectedBaseClass } from "../gir/introspected-classes.ts";
+import type { IntrospectedNamespace } from "../gir/namespace.ts";
+import { AnyType, GenericType, ThisType, type TypeExpression, TypeIdentifier } from "../gir.ts";
+import { TwoKeyMap } from "../util.ts";
+
+/**
+ * Resolves a class identifier.
+ *
+ * If the identifier is a class type it is returned,
+ * otherwise `null`.
+ *
+ * @param namespace
+ * @param type
+ */
+export function resolveTypeIdentifier(
+	namespace: IntrospectedNamespace,
+	type: TypeIdentifier,
+): IntrospectedBaseClass | null {
+	const ns = type.namespace;
+	const name = type.name;
+
+	const resolved_ns = namespace.assertInstalledImport(ns);
+
+	const pclass = resolved_ns.getClass(name);
+	if (pclass) {
+		return pclass;
+	} else {
+		return null;
+	}
+}
+
+/**
+ * Checks if two type expressions are in conflict (not equal)
+ * @param a
+ * @param b
+ */
+function isTypeConflict(a: TypeExpression, b: TypeExpression) {
+	return !a.equals(b) || !b.equals(a);
+}
+
+/**
+ * Checks if a given type expression in the context of a given this type
+ * is a subtype (compatible with) of another type expression in the context
+ * of a parent type.
+ *
+ * @param namespace
+ * @param thisType
+ * @param parentThisType
+ * @param potentialSubtype
+ * @param parentType
+ */
+export function isSubtypeOf(
+	namespace: IntrospectedNamespace,
+	thisType: TypeIdentifier,
+	parentThisType: TypeIdentifier,
+	potentialSubtype: TypeExpression,
+	parentType: TypeExpression,
+) {
+	if (!isTypeConflict(potentialSubtype, parentType)) {
+		return true;
+	}
+
+	const unwrappedSubtype = potentialSubtype.unwrap();
+	let unwrappedParent = parentType.unwrap();
+
+	if (
+		(potentialSubtype.equals(ThisType) && unwrappedParent.equals(thisType)) ||
+		(parentType.equals(ThisType) && unwrappedSubtype.equals(parentThisType))
+	) {
+		return true;
+	}
+
+	if (unwrappedParent instanceof GenericType && unwrappedParent.identifier !== "T") {
+		// Technically there could be a conflicting generic, but most generic types should specify a replacement for type checking.
+		// "T" denotes a local function generic in the current implementation, those can't be ignored.
+		if (!unwrappedParent.replacedType) {
+			return true;
+		}
+
+		// Use the generic replaced type as a stand-in.
+		unwrappedParent = unwrappedParent.replacedType;
+	}
+
+	if (!(unwrappedSubtype instanceof TypeIdentifier) || !(unwrappedParent instanceof TypeIdentifier)) {
+		return false;
+	}
+
+	const resolutions =
+		namespace.parent.subtypes.get(unwrappedSubtype.name, unwrappedSubtype.namespace) ??
+		new TwoKeyMap<string, string, boolean>();
+	const resolution = resolutions.get(unwrappedParent.name, unwrappedParent.namespace);
+
+	if (typeof resolution === "boolean") {
+		return resolution;
+	}
+
+	const resolved = resolveTypeIdentifier(namespace, unwrappedSubtype);
+
+	if (!resolved) {
+		return false;
+	}
+	const parentResolution = resolved.resolveParents();
+
+	// This checks that the two types have the same form, regardless of identifier (e.g. A | null and B | null)
+	const isStructurallySubtype = potentialSubtype.rewrap(AnyType).equals(parentType.rewrap(AnyType));
+
+	const isSubtype =
+		isStructurallySubtype &&
+		parentResolution.node.someParent((t: IntrospectedBaseClass) => t.getType().equals(unwrappedParent));
+
+	resolutions.set(unwrappedParent.name, unwrappedParent.namespace, isSubtype);
+
+	namespace.parent.subtypes.set(unwrappedSubtype.name, unwrappedSubtype.namespace, resolutions);
+
+	return isSubtype;
+}

package/src/utils/types.ts

@@ -0,0 +1,285 @@
+import type { GirAliasElement } from "@gi.ts/parser";
+import { GirDirection } from "@gi.ts/parser";
+import type { IntrospectedNamespace } from "../gir/namespace.ts";
+import {
+	AnyType,
+	ArrayType,
+	BigintOrNumberType,
+	BinaryType,
+	BooleanType,
+	NativeType,
+	NeverType,
+	NullableType,
+	NullType,
+	NumberType,
+	ObjectType,
+	OrType,
+	PromiseType,
+	RawPointerType,
+	StringType,
+	ThisType,
+	TupleType,
+	type TypeExpression,
+	TypeIdentifier,
+	Uint8ArrayType,
+	UnknownType,
+	VoidType,
+} from "../gir.ts";
+import { girParsingReporter } from "./gir-parsing.ts";
+
+/**
+ * Get the type expression for an alias element
+ */
+export function getAliasType(
+	namespace: string,
+	_ns: IntrospectedNamespace,
+	parameter: GirAliasElement,
+): TypeExpression {
+	let name = parameter.type?.[0].$.name || "unknown";
+
+	const nameParts = name.split(" ");
+
+	if (nameParts.length === 1) {
+		name = nameParts[0];
+	} else {
+		name = nameParts[1];
+	}
+
+	return parseTypeExpression(namespace, name);
+}
+
+/**
+ * Parse a type string into namespace and name components
+ */
+export function parseTypeString(type: string): { namespace: string | null; name: string } {
+	if (type.includes(".")) {
+		const parts = type.split(".");
+
+		if (parts.length > 2) {
+			throw new Error(`Invalid type string ${type} passed.`);
+		}
+
+		const [namespace, name] = parts;
+
+		return { name, namespace };
+	} else {
+		return { name: type, namespace: null };
+	}
+}
+
+/**
+ * Parse a type identifier from namespace and type string
+ */
+export function parseTypeIdentifier(namespace: string, type: string): TypeIdentifier {
+	const baseType = parseTypeString(type);
+
+	if (baseType.namespace) {
+		return new TypeIdentifier(baseType.name, baseType.namespace);
+	} else {
+		return new TypeIdentifier(baseType.name, namespace);
+	}
+}
+
+/**
+ * Parse a type expression from namespace and type string
+ */
+export function parseTypeExpression(namespace: string, type: string): TypeExpression {
+	const baseType = parseTypeString(type);
+	if (baseType.namespace) {
+		if (baseType.namespace === namespace) {
+			return new TypeIdentifier(baseType.name, namespace);
+		}
+		return new TypeIdentifier(baseType.name, baseType.namespace).sanitize();
+	} else {
+		const primitiveType = resolvePrimitiveType(baseType.name);
+
+		if (primitiveType !== null) {
+			return primitiveType;
+		} else {
+			return new TypeIdentifier(baseType.name, namespace);
+		}
+	}
+}
+
+/**
+ * Resolve primitive array types with their correct depth
+ */
+export function resolvePrimitiveArrayType(name: string, arrayDepth: number): [TypeExpression, number] | null {
+	if (arrayDepth > 0) {
+		switch (name) {
+			case "gint8":
+			case "guint8":
+				return [Uint8ArrayType, arrayDepth - 1];
+			case "gunichar":
+				return [StringType, arrayDepth - 1];
+		}
+	}
+
+	const resolvedName = resolvePrimitiveType(name);
+
+	if (resolvedName) {
+		return [resolvedName, arrayDepth];
+	} else {
+		return null;
+	}
+}
+
+/**
+ * Check if a type name is a primitive type
+ */
+export function isPrimitiveType(name: string): boolean {
+	return resolvePrimitiveType(name) !== null;
+}
+
+/**
+ * Resolve primitive type names to TypeExpression instances
+ */
+export function resolvePrimitiveType(name: string): TypeExpression | null {
+	switch (name) {
+		case "":
+			girParsingReporter.get().reportTypeResolutionWarning("", "unknown", "Resolving empty type name to 'any'");
+			return AnyType;
+		case "filename":
+			return StringType;
+		// Pass this through
+		case "GType":
+			return new TypeIdentifier("GType", "GObject");
+		case "utf8":
+			return StringType;
+		case "void": // Support TS "void"
+		case "none":
+			return VoidType;
+		// TODO Some libraries are bad and don't use g-prefixed numerical types
+		case "uint":
+		case "int":
+		case "uint8":
+		case "int8":
+		case "uint16":
+		case "int16":
+		case "uint32":
+		case "int32":
+		case "int64":
+		case "uint64":
+		case "double":
+		case "long":
+		case "float":
+		// Most libraries will use these though:
+		case "gshort":
+		case "guint32":
+		case "guint16":
+		case "gint16":
+		case "gint8":
+		case "gint32":
+		case "gushort":
+		case "gfloat":
+		case "gchar":
+		case "guint":
+		case "gint":
+		case "guint8":
+		case "gdouble":
+			return NumberType;
+		case "glong":
+		case "gulong":
+		case "guint64":
+		case "gint64":
+		case "gssize":
+		case "gsize":
+		case "guintptr": // Integer of the same width as a pointer
+		case "time_t": // C standard library time type (seconds since Unix epoch)
+		case "ulong": // C standard library unsigned long type
+			return BigintOrNumberType;
+		case "gboolean":
+			return BooleanType;
+		case "gpointer":
+			// You can't use pointers. Pointer arguments are mostly not exposed
+			// in GJS, but any exposed pointer arguments are always marshalled
+			// as null pointers. If the argument is nullable, this will combine
+			// with `null` to produce `null`, but if the argument isn't nullable
+			// it's impossible to pass a valid parameter to the function.
+			return RawPointerType;
+		case "object": // Support TS "object"
+			return ObjectType;
+		case "va_list":
+			return AnyType;
+		case "never": // Support TS "never"
+			return NeverType;
+		case "unknown": // Support TS "unknown"
+			return UnknownType;
+		case "any": // Support TS "any"
+			return AnyType;
+		case "this": // Support TS "this"
+			return ThisType;
+		case "number": // Support TS "number"
+			return NumberType;
+		case "gunichar":
+		case "string": // Support TS "string"
+			return StringType;
+		case "boolean": // Support TS "boolean"
+			return BooleanType;
+	}
+
+	return null;
+}
+
+/**
+ * Resolve directional types based on GIR direction
+ */
+export function resolveDirectedType(type: TypeExpression, direction: GirDirection): TypeExpression | null {
+	if (type instanceof ArrayType) {
+		if (
+			(direction === GirDirection.In || direction === GirDirection.Inout) &&
+			type.type.equals(Uint8ArrayType) &&
+			type.arrayDepth === 0
+		) {
+			return new BinaryType(type, StringType);
+		} else {
+			// Rewrap arrays if they have directional types
+			return type.rewrap(resolveDirectedType(type.type, direction) ?? type.type);
+		}
+	} else if (type instanceof TypeIdentifier) {
+		if ((direction === GirDirection.In || direction === GirDirection.Inout) && type.is("GLib", "Bytes")) {
+			return new BinaryType(type, Uint8ArrayType);
+		} else if (type.is("GObject", "Value")) {
+			if (direction === GirDirection.In || direction === GirDirection.Inout) {
+				return new BinaryType(type, AnyType);
+			} else {
+				// GJS converts GObject.Value out parameters to their unboxed type, which we don't know,
+				// so type as `unknown`
+				return UnknownType;
+			}
+		} else if (type.is("GLib", "HashTable")) {
+			if (direction === GirDirection.In) {
+				// Intentional `any` — GLib.HashTable maps to a JS dict with dynamic values in generated output
+				return new BinaryType(new NativeType("{ [key: string]: any }"), type);
+			} else {
+				return type;
+			}
+		}
+	} else if (type === BigintOrNumberType && direction === GirDirection.Out) {
+		// 64-bit integers accept number or bigint, but only return number to JS
+		return NumberType;
+	} else if (type === RawPointerType && direction === GirDirection.Out) {
+		// Raw pointers are always marshalled as JS null.
+		return NullType;
+	} else if (type instanceof PromiseType) {
+		// Propagate direction into the Promise's inner type so e.g. async
+		// functions returning 64-bit ints resolve to `Promise<number>` rather
+		// than `Promise<bigint | number>`.
+		const resolvedInner = resolveDirectedType(type.type, direction);
+		if (resolvedInner) return new PromiseType(resolvedInner);
+	} else if (type instanceof BinaryType && !(type instanceof NullableType)) {
+		// Walk through binary unions like `Promise<T> | void` (the dual-call
+		// async overload) so the inner types still get direction propagation.
+		// NullableType is skipped to preserve its subclass behaviour.
+		const a = resolveDirectedType(type.a, direction) ?? type.a;
+		const b = resolveDirectedType(type.b, direction) ?? type.b;
+		if (a !== type.a || b !== type.b) return new BinaryType(a, b);
+	} else if (type instanceof OrType && !(type instanceof BinaryType || type instanceof TupleType)) {
+		// flatten "bigint | number" out of another OR-type
+		const types = type.types.map((t) => resolveDirectedType(t, direction) ?? t);
+		if (types.length === 1) return types[0];
+		return new OrType(types[0], ...types.slice(1));
+	}
+
+	return null;
+}