@ts-for-gir/lib 4.0.0-beta.4 → 4.0.0-beta.40

package/src/utils/naming.ts

@@ -0,0 +1,188 @@
+import { RESERVED_NAMESPACE_NAMES } from "../constants.ts";
+import { isFirstCharNumeric, upperCamelCase } from "./strings.ts";
+
+// Reserved words for identifier sanitization
+const reservedWords = [
+	"abstract",
+	"arguments",
+	"await",
+	"boolean",
+	"break",
+	"byte",
+	"case",
+	"catch",
+	"char",
+	"class",
+	"const",
+	"continue",
+	"constructor", // This isn't technically reserved, but it's problematic.
+	"debugger",
+	"default",
+	"delete",
+	"do",
+	"else",
+	"enum",
+	"eval",
+	"export",
+	"extends",
+	"false",
+	"final",
+	"finally",
+	"for",
+	"function",
+	"goto",
+	"if",
+	"implements",
+	"import",
+	"in",
+	"instanceof",
+	"interface",
+	"let",
+	"native",
+	"new",
+	"null",
+	"package",
+	"private",
+	"protected",
+	"public",
+	"return",
+	"short",
+	"static",
+	"super",
+	"switch",
+	"synchronized",
+	"this",
+	"throw",
+	"throws",
+	"transient",
+	"true",
+	"try",
+	"typeof",
+	"var",
+	"void",
+	"volatile",
+	"while",
+	"with",
+	"yield",
+];
+
+// Map to store sanitized identifiers
+export const SanitizedIdentifiers = new Map<string, string>();
+
+/**
+ * Transform a package name to import name format (lowercase)
+ * @param packageName The package name to transform
+ * @returns The transformed import name
+ */
+export function transformImportName(packageName: string): string {
+	return packageName.toLowerCase();
+}
+
+/**
+ * Transform a module namespace name to the proper format
+ * Handles numeric names and reserved namespace names
+ * @param name The namespace name to transform
+ * @returns The transformed namespace name
+ */
+export function transformModuleNamespaceName(name: string): string {
+	// Handle numeric names - prepend 'TODO_' if name starts with a number
+	name = transformNumericName(name);
+
+	// Convert to upperCamelCase
+	name = upperCamelCase(name);
+
+	// Handle reserved namespace names
+	if (RESERVED_NAMESPACE_NAMES[name]) {
+		name = `${name}_`;
+	}
+
+	return name;
+}
+
+/**
+ * Transform names starting with numbers by prepending 'TODO_'
+ * In JavaScript there can be no variables, methods, class names or enum names that start with a number
+ * @param name The name to transform
+ * @returns The transformed name
+ */
+function transformNumericName(name: string): string {
+	if (isFirstCharNumeric(name)) {
+		name = `TODO_${name}`;
+	}
+	return name;
+}
+
+/**
+ * Sanitize identifier name to be valid JavaScript identifier
+ * @param namespace The namespace for the identifier (can be null)
+ * @param name The name to sanitize
+ * @returns The sanitized identifier name
+ */
+export function sanitizeIdentifierName(namespace: string | null, name: string): string {
+	// This is a unique case where the name is "empty".
+	if (name === "") {
+		return "''";
+	}
+
+	let sanitized_name = name.replace(/[^A-z0-9_]/gi, "_");
+
+	if (reservedWords.includes(sanitized_name)) {
+		sanitized_name = `__${sanitized_name}`;
+	}
+
+	if (sanitized_name.match(/^[^A-z_]/) != null) {
+		sanitized_name = `__${sanitized_name}`;
+	}
+
+	if (namespace && sanitized_name !== name) {
+		SanitizedIdentifiers.set(`${namespace}.${name}`, `${namespace}.${sanitized_name}`);
+	}
+
+	return sanitized_name;
+}
+
+/**
+ * Sanitize namespace name - fix broken namespacing in some GIRs
+ * @param namespace The namespace to sanitize
+ * @returns The sanitized namespace
+ */
+export function sanitizeNamespace(namespace: string): string {
+	if (namespace === "Tracker_Vala") {
+		return "Tracker";
+	}
+
+	return namespace;
+}
+
+/**
+ * Sanitize member names for safe usage
+ * @param name The member name to sanitize
+ * @returns The sanitized member name
+ */
+export function sanitizeMemberName(name: string): string {
+	// This is a unique case where the name is "empty".
+	if (name === "") {
+		return "''";
+	}
+
+	return name.replace(/[^A-z0-9_]/gi, "_");
+}
+
+/**
+ * Check if a name would be invalid as JavaScript identifier
+ * @param name The name to check
+ * @returns True if the name would be invalid
+ */
+export function isInvalid(name: string): boolean {
+	if (reservedWords.includes(name)) {
+		return true;
+	}
+
+	const sanitized = sanitizeMemberName(name);
+
+	if (sanitized.match(/^[^A-z_]/) != null) {
+		return true;
+	}
+
+	return false;
+}

package/src/utils/numbers.ts

@@ -0,0 +1,8 @@
+/**
+ * Checking whether a string is numeric
+ * @param str The string to check
+ * @returns Whether the string is numeric or not
+ */
+export const isNumeric = (str: string): boolean => {
+	return !Number.isNaN(Number(str) - parseFloat(str));
+};

package/src/utils/objects.ts

@@ -0,0 +1,129 @@
+import lodash from "lodash";
+
+export { inspect } from "node:util";
+
+/**
+ * Performs a deep comparison between two values to determine if they are
+ * equivalent.
+ *
+ * **Note:** This method supports comparing arrays, array buffers, booleans,
+ * date objects, error objects, maps, numbers, `Object` objects, regexes,
+ * sets, strings, symbols, and typed arrays. `Object` objects are compared
+ * by their own, not inherited, enumerable properties. Functions and DOM
+ * nodes are **not** supported.
+ *
+ * @category Lang
+ * @param value The value to compare.
+ * @param other The other value to compare.
+ * @returns Returns `true` if the values are equivalent, else `false`.
+ * @example
+ *
+ * var object = { 'user': 'fred' };
+ * var other = { 'user': 'fred' };
+ *
+ * _.isEqual(object, other);
+ * // => true
+ *
+ * object === other;
+ * // => 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).
+ *
+ * Many lodash methods are guarded to work as iteratees for methods like _.every, _.filter, _.map, _.mapValues,
+ * _.reject, and _.some.
+ *
+ * The guarded methods are:
+ * ary, callback, chunk, clone, create, curry, curryRight, drop, dropRight, every, fill, flatten, invert, max,
+ * min, parseInt, slice, sortBy, take, takeRight, template, trim, trimLeft, trimRight, trunc, random, range,
+ * sample, some, sum, uniq, and words
+ *
+ * @param collection The collection to iterate over.
+ * @param iteratee The function invoked per iteration.
+ * @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).
+ *
+ * @param collection The collection to search.
+ * @param predicate The function invoked per iteration.
+ * @param fromIndex The index to search from.
+ * @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
+ * to `undefined`. Array and plain object properties are merged recursively.
+ * Other objects and value types are overridden by assignment. Source objects
+ * are applied from left to right. Subsequent sources overwrite property
+ * assignments of previous sources.
+ *
+ * **Note:** This method mutates `object`.
+ *
+ * @category Object
+ * @param object The destination object.
+ * @param [sources] The source objects.
+ * @returns Returns `object`.
+ * @example
+ *
+ * var users = {
+ *   'data': [{ 'user': 'barney' }, { 'user': 'fred' }]
+ * };
+ *
+ * var ages = {
+ *   'data': [{ 'age': 36 }, { 'age': 40 }]
+ * };
+ *
+ * _.merge(users, ages);
+ * // => { 'data': [{ 'user': 'barney', 'age': 36 }, { 'user': 'fred', 'age': 40 }] }
+ */
+export const merge = lodash.merge;
+
+/**
+ * Creates a shallow clone of value.
+ *
+ * Note: This method is loosely based on the structured clone algorithm and supports cloning arrays,
+ * array buffers, booleans, date objects, maps, numbers, Object objects, regex's, sets, strings, symbols,
+ * and typed arrays. The own enumerable properties of arguments objects are cloned as plain objects. An empty
+ * object is returned for not cloneable values such as error objects, functions, DOM nodes, and WeakMaps.
+ *
+ * @param value The value to clone.
+ * @return Returns the cloned value.
+ */
+export const clone = lodash.clone;
+
+/**
+ * This method is like clone except that it recursively clones value.
+ *
+ * @param value The value to recursively 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: 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 = <T>(target: Set<T> | T[], source: Set<T> | T[]): Set<T> => {
+	return new Set<T>([...target, ...source]);
+};

package/src/utils/path.ts

@@ -0,0 +1,7 @@
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+// Get __filename on ESM
+const __filename = fileURLToPath(import.meta.url);
+// Get __dirname on ESM, resolve to the root directory of this package
+export const __dirname = resolve(dirname(__filename), "../.."); // TODO: Bundled this must be '..' but unbundled it must be '../..'

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;
+}