@ts-for-gir/cli 3.0.0-beta.8 → 3.0.0-beta.9

package/src/types/dependency-map.ts

@@ -1,4 +1,4 @@
 import { Dependency } from './dependency'
 export interface DependencyMap {
-    [name: string]: Dependency[]
+    [packageName: string]: Dependency[]
 }

package/src/types/dependency.ts

@@ -1,4 +1,6 @@
-export interface Dependency {
+import { FileInfo } from './file-info.js'
+
+export interface Dependency extends FileInfo {
     /**
      * E.g. 'Gtk'
      */

package/src/types/file-info.ts

@@ -0,0 +1,14 @@
+export interface FileInfo {
+    /**
+     * The path to the gir file or null if the file does not exist
+     */
+    path: string | null
+    /**
+     * The filename of the gir file
+     */
+    filename: string
+    /**
+     * Whether the file exists or not
+     */
+    exists: boolean
+}

package/src/types/generate-config.ts

@@ -16,20 +16,18 @@ export interface GenerateConfig {
     girDirectories: string[]
     /** Switch on/off the verbose mode */
     verbose: boolean
-    /** prettifies the generated .d.ts files */
-    pretty: boolean
-    /** Export all symbols for each module as a namespace */
-    useNamespace: boolean
+    /** Do not export all symbols for each module as a namespace */
+    noNamespace: boolean
     /** Do not generate documentation comments */
     noComments: boolean
     /** Do not generate debugging inline comments */
     noDebugComments: boolean
-    /** Disable typescript semantic checks using @ts-nocheck */
-    noCheck: boolean
     /** Fix Inheritance and implementation type conflicts */
     fixConflicts: boolean
     /** Disables the generation of types that are in conflict with the DOM types */
     noDOMLib: boolean
     /** Generate types for GNOME Shell */
     gnomeShellTypes: boolean
+    /** Generate a tsconfig alias */
+    generateAlias: boolean
 }

package/src/types/index.ts

@@ -9,6 +9,7 @@ export * from './construct-name.js'
 export * from './dependency-map.js'
 export * from './dependency.js'
 export * from './environment.js'
+export * from './file-info.js'
 export * from './generate-config.js'
 export * from './generator-type.js'
 export * from './gir-alias-element.js'

package/src/types/user-config.ts

@@ -20,24 +20,22 @@ export interface UserConfig {
     ignoreVersionConflicts: boolean
     /** print the output to console and create no files */
     print: boolean
-    /** prettifies the generated .d.ts files */
-    pretty: boolean
     /** GIR modules to load, e.g. 'Gio-2.0'. Accepts multiple modules */
     modules: string[]
     /** modules that should be ignored */
     ignore?: string[]
-    /** Export all symbols for each module as a namespace */
-    useNamespace: boolean
+    /** Do not export all symbols for each module as a namespace */
+    noNamespace: boolean
     /** Do not generate documentation comments */
     noComments: boolean
     /** Do not generate debugging inline comments */
     noDebugComments: boolean
-    /** Disable typescript semantic checks using @ts-nocheck */
-    noCheck: boolean
     /** Fix Inheritance and implementation type conflicts */
     fixConflicts: boolean
     /** Disables the generation of types that are in conflict with the DOM types */
     noDOMLib: boolean
     /** Generate types for GNOME Shell */
     gnomeShellTypes: boolean
+    /** Generate a tsconfig alias */
+    generateAlias: boolean
 }

package/src/utils.ts

@@ -4,7 +4,7 @@ import Path from 'path'
 import fs from 'fs'
 import { getTsconfig, TsConfigJsonResolved } from 'get-tsconfig'
 import { fileURLToPath } from 'url'
-import { Environment, GirInfoAttrs, TsType } from './types/index.js'
+import { Environment, GirInfoAttrs, TsType, FileInfo } from './types/index.js'
 import { inspect } from 'util'
 import { Logger } from './logger.js'
 
@@ -12,18 +12,115 @@ import { COMMENT_REG_EXP, PARAM_REG_EXP, OPT_PARAM_REG_EXP } from './constants.j
 
 export { inspect }
 
+/**
+ * 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
 
+/**
+ * Split a package name into namespace and version
+ */
 export const splitModuleName = (packageName: string): { packageName: string; namespace: string; version: string } => {
     // There are modules that use multiple hyphens like 'GUPnP-DLNA-1.0'
     const splits = packageName.split('-')
@@ -47,6 +144,9 @@ export const removeNamespace = (type: string, namespace: string) => {
 /** Remove class module name prefix */
 export const removeClassModule = removeNamespace
 
+/**
+ * Add namespace prefix
+ */
 export const addNamespace = (type: string, namespace: string) => {
     if (!type.startsWith(namespace + '.')) {
         type = namespace + '.' + type
@@ -56,30 +156,56 @@ export const addNamespace = (type: string, namespace: string) => {
 
 /**
  * Checking whether some variable is iterable
- * see https://stackoverflow.com/a/32538867
+ * @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'
 }
 
+/**
+ * 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 => {
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     return !isNaN((str as any) - parseFloat(str))
 }
 
+/**
+ * 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
+ * @param str The string to convert
+ * @returns The converted string
+ */
 export const camelCase = (str: string): string => {
     return str
         .replace(/\s(.)|(\s|-|_|\.)(.)/g, (a) => {
@@ -88,34 +214,50 @@ export const camelCase = (str: string): string => {
         .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 UpperCamelCase
+ * @param str The string to convert
+ * @returns The converted string
+ */
 export const upperCamelCase = (str: string): string => {
     str = camelCase(str)
     str = getFirstChar(str).toUpperCase() + str.slice(1)
     return str
 }
 
-export const findFileInDirs = (dirs: string[], filename: string): { path: string | null; exists: boolean } => {
-    let exists = false
+/**
+ * Find a file in a list of directories
+ * @param dirs The directories to search in
+ * @param filename The filename to search for
+ * @returns The file info
+ */
+export const findFileInDirs = (dirs: string[], filename: string): FileInfo => {
+    const FileInfo: FileInfo = {
+        path: null,
+        filename,
+        exists: false,
+    }
     for (const dir of dirs) {
         const filePath = Path.join(dir, filename)
-        exists = fs.existsSync(filePath)
-        if (exists) {
-            return {
-                path: filePath,
-                exists,
-            }
+        FileInfo.exists = fs.existsSync(filePath)
+        if (FileInfo.exists) {
+            FileInfo.path = filePath
+            return FileInfo
         }
     }
-    return {
-        path: null,
-        exists,
-    }
+
+    return FileInfo
 }
 
 /**
@@ -141,19 +283,37 @@ export const stripParamNames = (func: string, ignoreTail = false): string => {
     return `${lb[0]}(${params})${tail}`
 }
 
+/**
+ * Check if a line is a comment line
+ * @param line The line to check
+ * @returns Whether the line is a comment line or not
+ */
 export const isCommentLine = (line: string) => {
     const lineTrim = line.trim()
     return lineTrim.startsWith('//') || (lineTrim.startsWith('/*') && lineTrim.endsWith('*/'))
 }
 
+/**
+ * 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)
 }
 
-// Get __dirname on ESM
+// Get __filename on ESM
 export const __filename = fileURLToPath(import.meta.url)
+// Get __dirname on ESM
 export const __dirname = Path.dirname(__filename)
 
+/**
+ * Get the output or input directory of the environment
+ * @param environment The environment to get the directory for
+ * @param baseDir The base directory
+ * @returns The path to the directory
+ */
 export const getEnvironmentDir = (environment: Environment, baseDir: string): string => {
     if (!baseDir.endsWith(environment))
         if (environment === 'gjs' && !baseDir.endsWith('/Gjs')) {
@@ -165,12 +325,25 @@ export const getEnvironmentDir = (environment: Environment, baseDir: string): st
     return baseDir
 }
 
+/**
+ * Get the destination path for the environment
+ * @param environment The environment to get the destination path for
+ * @param outputDir The output directory
+ * @param parts The path parts
+ * @returns The destination path
+ */
 export const getDestPath = (environment: Environment, outputDir: string, ...parts: string[]) => {
     const outputEnvDir = getEnvironmentDir(environment, outputDir)
     const destPath = Path.join(outputEnvDir, ...parts)
     return destPath
 }
 
+/**
+ * Convert a GirBoolean to a boolean
+ * @param boolStr The GirBoolean string
+ * @param defaultVal The default value
+ * @returns The boolean value
+ */
 export const girBool = (boolStr: string | undefined, defaultVal = false): boolean => {
     if (boolStr) {
         if (parseInt(boolStr) === 0) return false
@@ -210,6 +383,11 @@ export const girElementIsIntrospectable = (girElement?: { $: GirInfoAttrs & { na
     return true
 }
 
+/**
+ * Check if a type is optional
+ * @param types The types to check
+ * @returns Whether the type is optional or not
+ */
 export const typeIsOptional = (types: TsType[]) => {
     for (const type of types) {
         if (type.optional) return true
@@ -217,7 +395,12 @@ export const typeIsOptional = (types: TsType[]) => {
     return false
 }
 
-function convertTsJsConfigToObject(path: string) {
+/**
+ * Get a typescript or javascript config by path
+ * @param path The path to search for a tsconfig.json or jsconfig.json file
+ * @returns The config or null if not found
+ */
+export const getTsJsConfigByPath = (path: string) => {
     try {
         const config = getTsconfig(path)?.config
         if (config) return config
@@ -240,8 +423,8 @@ export function readTsJsConfig(path: string) {
         const tsConfigPath = Path.join(currentPath, 'tsconfig.json')
         const jsConfigPath = Path.join(currentPath, 'jsconfig.json')
         config =
-            (fs.existsSync(tsConfigPath) && convertTsJsConfigToObject(tsConfigPath)) ||
-            (fs.existsSync(jsConfigPath) && convertTsJsConfigToObject(jsConfigPath))
+            (fs.existsSync(tsConfigPath) && getTsJsConfigByPath(tsConfigPath)) ||
+            (fs.existsSync(jsConfigPath) && getTsJsConfigByPath(jsConfigPath))
         lastPath = currentPath
         currentPath = Path.dirname(currentPath)
     }

package/templates/Gjs/Gjs.d.ts

@@ -1,10 +1,13 @@
-<% if(useNamespace){ %>
-import GObject from './GObject-2.0.js';
-import GLib from './GLib-2.0.js';
-<% } else { %>
-import * as GObject from './GObject-2.0.js';
-import * as GLib from './GLib-2.0.js';
-<% } %>
+<% const gobject = dep.find('GObject') %>
+<% const glib = dep.find('GLib') %>
+
+<%_ if(noNamespace){ _%>
+    import type * as GObject from './<%= gobject.packageName %>.js';
+    import type * as GLib from './<%= glib.packageName %>.js';
+<%_ } else { _%>
+    import type GObject from './<%= gobject.packageName %>.js';
+    import type GLib from './<%= glib.packageName %>.js';
+<%_ } _%>
 
 // https://gitlab.gnome.org/GNOME/gjs/-/blob/1.72.0/modules/script/package.js
 export namespace Package {
@@ -133,5 +136,69 @@ export namespace Mainloop {
 }
 
 export namespace Signals {
-    export function addSignalMethods(proto: object): void
+
+    /**
+     * You can use the `Signals.addSignalMethods` method to apply the `Signals` convenience methods to an `Object`.
+     * Generally, this is called on an object prototype, but may also be called on an object instance.
+     * You can use this Interface for this object or prototype to make the methods in typescript known
+     * @example
+     * ```ts
+     * const Signals = imports.signals;
+     * 
+     * // Define an interface with the same name of your class to make the methods known
+     * interface Events extends Signals.Methods {}
+     * 
+     * class Events {}
+     * Signals.addSignalMethods(Events.prototype);
+     * 
+     * const events = new Events();
+     * 
+     * // Typescript will not complain here
+     * events.emit("test-signal", "test argument");
+     * ```
+     */
+    export interface Methods {
+        /**
+         * Connects a callback to a signal for an object. Pass the returned ID to
+         * `disconect()` to remove the handler.
+         * 
+         * If `callback` returns `true`, emission will stop and no other handlers will be
+         * invoked.
+         * 
+         * > Warning: Unlike GObject signals, `this` within a signal callback will always
+         * > refer to the global object (ie. `globalThis`).
+         * 
+         * @param sigName A signal name
+         * @param callback A callback function
+         * @returns A handler ID
+         */
+        connect(sigName: string, callback: (self: any, ...args: any[]) => void): number;
+        /**
+         * Emits a signal for an object. Emission stops if a signal handler returns `true`.
+         * 
+         * Unlike GObject signals, it is not necessary to declare signals or define their
+         * signature. Simply call `emit()` with whatever signal name you wish, with
+         * whatever arguments you wish.
+         * @param sigName A signal name
+         * @param args Any number of arguments, of any type
+         */
+        emit(sigName: string, ...args: any[]): void;
+        /**
+         * Disconnects a handler for a signal.
+         * @param id The ID of the handler to be disconnected
+         */
+        disconnect(id: number): void;
+        /**
+         * Disconnects all signal handlers for an object.
+         */
+        disconnectAll(): void
+        /**
+         * Checks if a handler ID is connected.
+         * @param id The ID of the handler to be disconnected
+         * @returns `true` if connected, or `false` if not
+         */
+        signalHandlerIsConnected(id: number): boolean;
+    }
+
+    export function addSignalMethods<T = any>(proto: T): proto is T & Methods;
 }