@ts-for-gir/templates 4.0.0-beta.40 → 4.0.0-beta.42

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ts-for-gir/templates",
-  "version": "4.0.0-beta.40",
+  "version": "4.0.0-beta.42",
   "description": "Templates for ts-for-gir",
   "type": "module",
   "main": "package.json",

package/templates/gio-2.0.d.ts

@@ -13,7 +13,7 @@
  * @param asyncFunc - The name of the asynchronous function.
  * @param finishFunc - The name of the "finish" function that is used to retrieve the result of the asynchronous function.
  *
- * @version Gjs 1.54
+ * @since 1.54
  * @see https://gjs.guide/guides/gjs/asynchronous-programming.html#promisify-helper
  *
  * @example

package/templates/gjs/dom.d.ts

@@ -34,7 +34,7 @@ declare global {
     // See https://gitlab.gnome.org/GNOME/gjs/-/blob/master/modules/esm/_timers.js
 
     /**
-     * @version Gjs 1.71.1
+     * @since 1.71.1
      * @param callback a callback function
      * @param delay the duration in milliseconds to wait before running callback
      * @param args arguments to pass to callback
@@ -42,7 +42,7 @@ declare global {
     function setTimeout(callback: (...args: any[]) => any, delay?: number, ...args: any[]): GLib.Source
 
     /**
-     * @version Gjs 1.71.1
+     * @since 1.71.1
      * @param callback a callback function
      * @param delay the duration in milliseconds to wait between calling callback
      * @param args arguments to pass to callback
@@ -50,13 +50,13 @@ declare global {
     function setInterval(callback: (...args: any[]) => any, delay?: number, ...args: any[]): GLib.Source
 
     /**
-     * @version Gjs 1.71.1
+     * @since 1.71.1
      * @param timeout the timeout to clear
      */
     function clearTimeout(timeout: GLib.Source): void
 
     /**
-     * @version Gjs 1.71.1
+     * @since 1.71.1
      * @param timeout the timeout to clear
      */
     function clearInterval(timeout: GLib.Source): void
@@ -244,7 +244,7 @@ declare global {
      * The TextDecoder interface represents a decoder for a specific text encoding.
      * It takes a stream of bytes as input and emits a stream of code points.
      *
-     * @version Gjs 1.69.2
+     * @since 1.69.2
      */
     interface TextDecoder {
         /** A string containing the name of the decoder, that is a string describing the method the TextDecoder will use. */
@@ -273,7 +273,7 @@ declare global {
     /**
      * TextEncoder takes a stream of code points as input and emits a stream of bytes.
      *
-     * @version Gjs 1.69.2
+     * @since 1.69.2
      */
     interface TextEncoder {
         readonly encoding: 'utf-8'

package/templates/gjs/gi.d.ts

@@ -0,0 +1,36 @@
+<%_ if(!package){ -%>
+declare module 'gi' {
+<% } -%>
+
+/**
+ * Requires a GObject Introspection namespace, optionally at a specific version.
+ * If a version is specified and a different version of the same namespace is
+ * already loaded, an error will be thrown.
+ *
+ * @param namespace The GI namespace to import (e.g. 'Gtk', 'GLib')
+ * @param version The version of the namespace (e.g. '4.0', '2.0')
+ * @returns The imported namespace module
+ */
+export function require(namespace: string, version?: string): any
+
+/**
+ * The `gi` module provides a single entry point for importing GObject
+ * Introspection namespaces in GJS ESM modules.
+ *
+ * @example
+ * ```ts
+ * import Gi from 'gi';
+ * Gi.require('Gtk', '4.0');
+ * ```
+ *
+ * @see https://gjs-docs.gnome.org/gjs/overrides.md#gi-require
+ */
+<%- package ? 'declare' : '' %> const Gi: {
+    readonly require: typeof require;
+}
+
+export default Gi
+
+<%_ if(!package){ -%>
+}
+<% } -%>

package/templates/gjs/gi.js

@@ -0,0 +1,4 @@
+import Gi, { require } from 'gi';
+
+export { require };
+export default Gi;

package/templates/gjs/gjs-ambient.d.ts

@@ -24,3 +24,9 @@ declare module 'console' {
     export { setConsoleLogDomain, getConsoleLogDomain, DEFAULT_LOG_DOMAIN }
     export default Console
 }
+
+declare module 'gi' {
+    import Gi, { require } from '@girs/gjs/gi'
+    export { require }
+    export default Gi
+}

package/templates/gjs/gjs.d.ts

@@ -10,6 +10,7 @@
 /// <reference path="./gettext.d.ts" />
 /// <reference path="./system.d.ts" />
 /// <reference path="./cairo.d.ts" />
+/// <reference path="./gi.d.ts" />
 <% } -%>
 
 /**
@@ -718,34 +719,50 @@ declare global {
         /**
          * Formats a string with the given arguments.
          * This method is made available by calling `pkg.initFormat()`.
-         * 
+         *
          * Supported format specifiers:
          * - %s: Formats as a string
          * - %d: Formats as an integer
          * - %x: Formats as a hexadecimal number
          * - %f: Formats as a floating point number, optionally with precision (e.g. %.2f)
-         * 
+         *
          * All specifiers can be prefixed with a minimum field width, e.g. "%5s" will pad with spaces.
          * If the width is prefixed with '0', it will pad with zeroes instead of spaces.
-         * 
+         *
          * @example
          * ```ts
          * // After calling pkg.initFormat()
          * "Hello %s, you have %d items".format("User", 5);
          * // Returns: "Hello User, you have 5 items"
-         * 
+         *
          * "Price: $%.2f".format(10.5);
          * // Returns: "Price: $10.50"
-         * 
+         *
          * "ID: %05d".format(42);
          * // Returns: "ID: 00042"
          * ```
-         * 
+         *
          * @param args The arguments to format the string with
          * @returns The formatted string
          */
         format(...args: (string | number | boolean | null | undefined)[]): string;
     }
+
+    interface Error {
+        /**
+         * Checks if this error matches a GLib error domain and code.
+         *
+         * Added to the global `Error` prototype by the GLib override so that
+         * `e.matches(Ns.FooError, Ns.FooError.SOME_CODE)` works without an
+         * `instanceof` check. Always returns `false` for standard JavaScript
+         * errors; only `GLib.Error` instances provide a meaningful implementation.
+         *
+         * @param domain A GLib error domain (error class constructor or quark)
+         * @param code The error code to match against
+         * @returns `false` for native JS errors, `true` if a GLib.Error matches
+         */
+        matches(domain: unknown, code: number): boolean;
+    }
 }
 
 declare const _imports: GjsImports

package/templates/gjs/system.d.ts

@@ -14,7 +14,7 @@ declare module 'system' {
  * line. In C and other languages, this information is contained in the first element of
  * the platform's equivalent of argv, but GJS's ARGV only contains the
  * subsequent command-line arguments. In other words, `ARGV[0]` in GJS is the same as `argv[1]` in C.
- * @version Gjs 1.68
+ * @since 1.68
  */
 export const programInvocationName: string
 
@@ -25,7 +25,7 @@ export const version: number
 
 /**
  * The full path of the executed program.
- * @version Gjs 1.68
+ * @since 1.68
  */
 export const programPath: string | null
 
@@ -33,7 +33,7 @@ export const programPath: string | null
  * A list of arguments passed to the current process.
  * This is effectively an alias for the global `ARGV`, which is misleading in that
  * it is not equivalent to the platform'`s` argv.
- * @version Gjs 1.68
+ * @since 1.68
  */
 export const programArgs: string[]
 
@@ -55,7 +55,7 @@ export function addressOf(o: object): string
  * See also {@link addressOf}
  * @param o Any {@link GObject.Object}-derived instance
  * @returns A hexadecimal string (e.g. `0xb4f170f0`)
- * @version Gjs 1.58
+ * @since 1.58
  */
 export function addressOfGObject(o: GObject.Object): string
 
@@ -119,7 +119,7 @@ export function dumpHeap(path?: string): void
  * Dump internal garbage collector statistics. If `path` is not given, GJS will
  * write the contents to `stdout`.
  * @param path Optional file path
- * @version Gjs 1.70
+ * @since 1.70
  * @example Output:
  * ```json
  * {

package/templates/glib-2.0.d.ts

@@ -989,7 +989,7 @@ export class Variant<S extends string = any> {
      * @returns The recursively unpacked JavaScript value with all Variants converted to native types
      * @see {@link deepUnpack} for one-level unpacking with type preservation
      * @see {@link unpack} for shallow unpacking only
-     * @since GJS 1.64 (GNOME 3.36)
+     * @since 1.64
      */
     recursiveUnpack(): $ParseRecursiveVariant<S>;
     recursiveUnpack<T>(): T;

package/templates/package.json

@@ -49,6 +49,11 @@ _%>
         "import": "./console.js",
         "default": "./console.js"
       },
+      "./gi": {
+        "types": "./gi.d.ts",
+        "import": "./gi.js",
+        "default": "./gi.js"
+      },
       <%_ } else {_%>
       "./import": {
         "types": "./<%- entryPointName %>-import.d.ts",

package/templates/tsconfig.json

@@ -3,9 +3,31 @@ let includes = []
 let entryPointName = importName
 if (packageName === 'Gjs') {
   entryPointName = 'gjs'
-  includes.push(`./dom.d.ts`)
+  includes.push('./dom.d.ts')
+  includes.push('./cairo.d.ts')
+  includes.push('./gettext.d.ts')
+  includes.push('./system.d.ts')
+  includes.push('./console.d.ts')
+  includes.push('./gjs-ambient.d.ts')
 }
 includes.push(`./${entryPointName}.d.ts`)
+
+// Build paths mappings for cross-package type resolution (needed for TypeDoc inheritance)
+let paths = {}
+if (typeof girModule !== 'undefined' && girModule && girModule.transitiveDependencies) {
+  girModule.transitiveDependencies.forEach(dependency => {
+    if (girModule.packageName !== dependency.packageName && dependency.exists) {
+      paths[dependency.importPath] = [`../${dependency.importName}/index.d.ts`]
+    }
+  })
+}
+if (packageName !== 'Gjs' && typeof dep !== 'undefined' && dep) {
+  const Gjs = await dep.getGjs()
+  if (Gjs && Gjs.importPath) {
+    paths[Gjs.importPath] = [`../gjs/index.d.ts`]
+  }
+}
+const hasPaths = Object.keys(paths).length > 0
 _%>
 {
   "compilerOptions": {
@@ -26,7 +48,9 @@ _%>
     "inlineSources": false,
     "newLine": "LF",
     // Show diagnostics
-    "diagnostics": true
+    "diagnostics": true<%_ if (hasPaths) { _%>,
+    "paths": <%- JSON.stringify(paths, null, 6) %>
+    <%_ } _%>
   },
   "include": <%- JSON.stringify(includes) %>
 }

package/templates/typedoc.json

@@ -7,11 +7,11 @@ if (packageName === 'Gjs') {
 let entryPoints = [`./${entryPointName}.d.ts`]
 
 if (packageName === 'Gjs') {
-  // entryPoints.push(`./ambient.d.ts`)
-  // entryPoints.push(`./cairo.d.ts`)
-  // entryPoints.push(`./gettext.d.ts`)
-  // entryPoints.push(`./system.d.ts`)
-  // entryPoints.push('./dom.d.ts')
+  entryPoints.push('./cairo.d.ts')
+  entryPoints.push('./gettext.d.ts')
+  entryPoints.push('./system.d.ts')
+  entryPoints.push('./dom.d.ts')
+  entryPoints.push('./console.d.ts')
 } else {
   // entryPoints.push(`./${entryPointName}-ambient.d.ts`)
   // entryPoints.push(`./${entryPointName}-import.d.ts`)
@@ -22,5 +22,7 @@ _%>
     "entryPoints": <%- JSON.stringify(entryPoints) %>,
     "readme": "./README.md",
     "name": "<%- packageName %>",
-    "tsconfig": "./tsconfig.json"
+    "tsconfig": "./tsconfig.json",
+    "skipErrorChecking": true,
+    "highlightLanguages": ["typescript", "javascript", "c", "cpp", "xml", "bash", "json", "css"]
 }