@girs/gjs 4.0.0-beta.9 → 4.0.0-rc.2

package/console.d.ts

@@ -0,0 +1,21 @@
+/**
+ * @param logDomain the GLib log domain this Console should print
+ *   with. Defaults to 'Gjs-Console'.
+ */
+export function setConsoleLogDomain(logDomain: string): void;
+
+/**
+ * @param logDomain the GLib log domain this Console should print
+ *   with. Defaults to 'Gjs-Console'.
+ */
+export function getConsoleLogDomain(): string;
+
+export declare const DEFAULT_LOG_DOMAIN: string;
+
+declare const Console: {
+    setConsoleLogDomain: typeof setConsoleLogDomain;
+    getConsoleLogDomain: typeof getConsoleLogDomain;
+    DEFAULT_LOG_DOMAIN: typeof DEFAULT_LOG_DOMAIN;
+};
+
+export default Console;

package/console.js

@@ -0,0 +1,6 @@
+import Console, { getConsoleLogDomain, setConsoleLogDomain, DEFAULT_LOG_DOMAIN } from 'console';
+
+export { getConsoleLogDomain, setConsoleLogDomain, DEFAULT_LOG_DOMAIN }
+export default Console;
+
+

package/dom.d.ts

@@ -10,6 +10,7 @@
  */
 
 import type GLib from '@girs/glib-2.0';
+import type GObject from '@girs/gobject-2.0';
 
 declare global {
     interface ImportMeta {
@@ -18,14 +19,14 @@ declare global {
          *
          * @see https://gitlab.gnome.org/GNOME/gjs/-/blob/master/doc/ESModules.md#importmetaurl
          */
-        readonly url: string;
+        url: string; // with readonly this type is incompatible with e.g. https://github.com/vitejs/vite/blob/main/packages/vite/types/importMeta.d.ts
     }
 
     // Timers
     // 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
@@ -33,7 +34,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
@@ -41,13 +42,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;
@@ -217,18 +218,6 @@ declare global {
          * @param _label unique identifier for this action
          */
         timeStamp(_label: string): void;
-
-        // GJS-specific extensions for integrating with GLib structured logging
-
-        /**
-         * @param logDomain the GLib log domain this Console should print
-         *   with. Defaults to 'Gjs-Console'.
-         */
-        setLogDomain(logDomain: string): void;
-
-        logDomain: string;
-
-        interact(): void;
     }
 
     interface TextDecodeOptions {
@@ -247,7 +236,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. */
@@ -276,7 +265,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/gi.d.ts

@@ -0,0 +1,28 @@
+/**
+ * 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
+ */
+declare const Gi: {
+    readonly require: typeof require;
+};
+
+export default Gi;

package/gi.js

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

package/gjs-ambient.d.ts

@@ -17,3 +17,15 @@ declare module 'cairo' {
     import Cairo from '@girs/gjs/cairo';
     export default Cairo;
 }
+
+declare module 'console' {
+    import Console, { setConsoleLogDomain, getConsoleLogDomain, DEFAULT_LOG_DOMAIN } from '@girs/gjs/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/gjs.d.ts

@@ -40,24 +40,54 @@ declare namespace package {
         datadir?: string;
     }
 
-    /** The base name of the entry point (eg. org.foo.Bar.App) */
-    export const name: string | undefined;
-    /** The version of the package */
-    export const version: string | undefined;
-    /** The prefix of the package */
-    export const prefix: string | undefined;
-    /** The final datadir when installed; usually, these would be prefix + '/share' */
-    export const datadir: string | undefined;
-    /** The final libdir when installed; usually, these would be prefix + '/lib' (or '/lib64') */
-    export const libdir: string | undefined;
-    /** The final pkgdatadir when installed; usually, this would be prefix + '/share' */
-    export const pkgdatadir: string | undefined;
-    /** The final pkglibdir when installed; usually, this would be prefix + '/lib' (or '/lib64') */
-    export const pkglibdir: string | undefined;
-    /** The final moduledir when installed; usually, this would be prefix + '/lib' (or '/lib64') */
-    export const moduledir: string | undefined;
-    /** The directory containing gettext translation files; this will be datadir + '/locale' when installed and './po' in the source tree */
-    export const localedir: string | undefined;
+    /**
+     * The base name of the entry point (eg. org.foo.Bar.App)
+     *
+     * Note: Run `pkg.init()` before accessing this property.
+     */
+    export const name: string;
+    /**
+     * The version of the package
+     *
+     * Note: Run `pkg.init()` before accessing this property.
+     */
+    export const version: string;
+    /**
+     * The prefix of the package
+     *
+     * Note: Run `pkg.init()` before accessing this property.
+     */
+    export const prefix: string;
+    /**
+     * The final datadir when installed; usually, these would be prefix + '/share'
+     *
+     * Note: Run `pkg.init()` before accessing this property.
+     */
+    export const datadir: string;
+    /**
+     * The final libdir when installed; usually, these would be prefix + '/lib' (or '/lib64')
+     *
+     * Note: Run `pkg.init()` before accessing this property.
+     */
+    export const libdir: string;
+    /**
+     * The final pkglibdir when installed; usually, this would be prefix + '/lib' (or '/lib64')
+     *
+     * Note: Run `pkg.init()` before accessing this property.
+     */
+    export const pkglibdir: string;
+    /**
+     * The final moduledir when installed; usually, this would be prefix + '/lib' (or '/lib64')
+     *
+     * Note: Run `pkg.init()` before accessing this property.
+     */
+    export const moduledir: string;
+    /**
+     * The directory containing gettext translation files; this will be datadir + '/locale' when installed and './po' in the source tree
+     *
+     * Note: Run `pkg.init()` before accessing this property.
+     */
+    export const localedir: string;
 
     /**
      * Initialize directories and global variables. Must be called
@@ -165,7 +195,31 @@ declare namespace package {
      */
     export function initGettext(): void;
     /**
-     * @deprecated Use JS string interpolation
+     * Initializes string formatting capabilities by adding a format() method to String.prototype.
+     *
+     * After calling this method, you can use a printf-style string formatting by calling
+     * the format() method on any string:
+     *
+     * @example
+     * ```ts
+     * pkg.initFormat();
+     *
+     * // Now you can use format() on any string
+     * const name = "User";
+     * const count = 5;
+     * const formatted = "Hello %s, you have %d items".format(name, count);
+     * // formatted = "Hello User, you have 5 items"
+     *
+     * // Format numbers with precision
+     * const price = 10.5;
+     * const priceStr = "Price: $%.2f".format(price);
+     * // priceStr = "Price: $10.50"
+     *
+     * // Pad with zeros
+     * const id = 42;
+     * const idStr = "ID: %05d".format(id);
+     * // idStr = "ID: 00042"
+     * ```
      */
     export function initFormat(): void;
     /**
@@ -220,21 +274,49 @@ declare namespace lang {
 }
 
 declare namespace format {
-    export function vprintf(str: string, args: string[]): string;
-    export function printf(fmt: string, ...args: any[]): void;
-    // Following docs from gjs/modules/format.js
     /**
-     * This function is intended to extend the String object and provide
-     * an String.format API for string formatting.
-     * It has to be set up using String.prototype.format = Format.format;
-     * Usage:
-     * "somestring %s %d".format('hello', 5);
-     * It supports %s, %d, %x and %f, for %f it also support precisions like
-     * "%.2f".format(1.526). All specifiers can be prefixed with a minimum
-     * field width, e.g. "%5s".format("foo"). Unless the width is prefixed
-     * with '0', the formatted string will be padded with spaces.
+     * Formats a string using printf-style format specifiers.
+     *
+     * @param str The format string
+     * @param args The arguments to be formatted
+     * @returns The formatted string
+     */
+    export function vprintf(str: string, args: (string | number | boolean | null | undefined)[]): string;
+
+    /**
+     * Prints a formatted string to the console.
+     * Similar to C's printf function.
+     *
+     * @param fmt The format string
+     * @param args The arguments to be formatted
+     */
+    export function printf(fmt: string, ...args: (string | number | boolean | null | undefined)[]): void;
+
+    /**
+     * Formats a string with the given arguments.
+     * This is the implementation that backs String.prototype.format
+     * when pkg.initFormat() is called.
+     *
+     * 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
+     * format.format("Hello %s, you have %d items", "User", 5);
+     * // Returns: "Hello User, you have 5 items"
+     * ```
+     *
+     * @param fmt The format string
+     * @param args The arguments to format the string with
+     * @returns The formatted string
      */
-    export function format(fmt: string, ...args: any[]): string;
+    export function format(fmt: string, ...args: (string | number | boolean | null | undefined)[]): string;
 }
 
 declare namespace mainloop {
@@ -566,17 +648,17 @@ declare global {
      * Run `pkg.initGettext()` before using this.
      * See {@link gettext.gettext}
      */
-    const _: undefined | typeof gettext.gettext;
+    const _: typeof gettext.gettext;
     /**
      * Run `pkg.initGettext()` before using this.
      * See {@link gettext.pgettext}
      */
-    const C_: undefined | typeof gettext.pgettext;
+    const C_: typeof gettext.pgettext;
     /**
      * Run `pkg.initGettext()` before using this.
      * Currently not implemented.
      */
-    const N_: undefined | ((x: string) => string);
+    const N_: (x: string) => string;
 
     function print(...args: any[]): void;
     function printerr(...args: any[]): void;
@@ -599,9 +681,66 @@ declare global {
         $gtype: GObject.GType<string>;
     }
 
+    interface StringConstructor {
+        $gtype: GObject.GType<string>;
+    }
+
+    interface ObjectConstructor {
+        $gtype: GObject.GType<Object>;
+    }
+
     const imports: GjsImports;
 
     const ARGV: string[];
+
+    interface String {
+        /**
+         * 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/package.json

@@ -1,74 +1,79 @@
 {
-  "name": "@girs/gjs",
-  "version": "4.0.0-beta.9",
-  "description": "GJS TypeScript type definitions for Gjs",
-  "type": "module",
-  "module": "gjs.js",
-  "main": "gjs.js",
-  "exports": {
-    "./ambient": {
-      "types": "./gjs-ambient.d.ts",
-      "import": "./gjs-ambient.js",
-      "default": "./gjs-ambient.js"
+    "name": "@girs/gjs",
+    "version": "4.0.0-rc.2",
+    "description": "GJS TypeScript type definitions for Gjs",
+    "type": "module",
+    "module": "gjs.js",
+    "main": "gjs.js",
+    "exports": {
+      "./ambient": {
+        "types": "./gjs-ambient.d.ts",
+        "import": "./gjs-ambient.js",
+        "default": "./gjs-ambient.js"
+      },
+      "./dom": {
+        "types": "./dom.d.ts",
+        "import": "./dom.js",
+        "default": "./dom.js"
+      },
+      "./gettext": {
+        "types": "./gettext.d.ts",
+        "import": "./gettext.js",
+        "default": "./gettext.js"
+      },
+      "./system": {
+        "types": "./system.d.ts",
+        "import": "./system.js",
+        "default": "./system.js"
+      },
+      "./cairo": {
+        "types": "./cairo.d.ts",
+        "import": "./cairo.js",
+        "default": "./cairo.js"
+      },
+      "./console": {
+        "types": "./console.d.ts",
+        "import": "./console.js",
+        "default": "./console.js"
+      },
+      "./gi": {
+        "types": "./gi.d.ts",
+        "import": "./gi.js",
+        "default": "./gi.js"
+      },
+      "./gjs": {
+        "types": "./gjs.d.ts",
+        "import": "./gjs.js",
+        "default": "./gjs.js"
+      },
+      ".": {
+        "types": "./index.d.ts",
+        "import": "./index.js",
+        "default": "./index.js"
+      }
     },
-    "./dom": {
-      "types": "./dom.d.ts",
-      "import": "./dom.js",
-      "default": "./dom.js"
+    "scripts": {
+      "test": "tsc --project tsconfig.json"
     },
-    "./gettext": {
-      "types": "./gettext.d.ts",
-      "import": "./gettext.js",
-      "default": "./gettext.js"
+    "dependencies": {
+      "@girs/gobject-2.0": "2.88.0-4.0.0-rc.2",
+      "@girs/glib-2.0": "2.88.0-4.0.0-rc.2",
+      "@girs/gio-2.0": "2.88.0-4.0.0-rc.2",
+      "@girs/cairo-1.0": "1.0.0-4.0.0-rc.2"    },
+    "devDependencies": {
+      "typescript": "*"
     },
-    "./system": {
-      "types": "./system.d.ts",
-      "import": "./system.js",
-      "default": "./system.js"
+    "keywords": ["Gir", "TypeScript", "types", "GObject-Introspection", "GJS", "Gjs"],
+    "author": "ts-for-gir",
+    "license": "MIT",
+    "repository": {
+      "type": "git",
+      "url": "git+https://github.com/gjsify/types.git"
     },
-    "./cairo": {
-      "types": "./cairo.d.ts",
-      "import": "./cairo.js",
-      "default": "./cairo.js"
+    "bugs": {
+      "url": "https://github.com/gjsify/ts-for-gir/issues"
     },
-    "./gjs": {
-      "types": "./gjs.d.ts",
-      "import": "./gjs.js",
-      "default": "./gjs.js"
-    },
-    ".": {
-      "types": "./index.d.ts",
-      "import": "./index.js",
-      "default": "./index.js"
-    }
-  },
-  "scripts": {
-    "test": "tsc --project tsconfig.json"
-  },
-  "dependencies": {
-    "@girs/gio-2.0": "^2.80.2-4.0.0-beta.9",
-    "@girs/glib-2.0": "^2.80.2-4.0.0-beta.9",
-    "@girs/gobject-2.0": "^2.80.2-4.0.0-beta.9"
-  },
-  "devDependencies": {
-    "typescript": "*"
-  },
-  "keywords": [
-    "Gir",
-    "TypeScript",
-    "types",
-    "GObject-Introspection",
-    "GJS",
-    "Gjs"
-  ],
-  "author": "ts-for-gir",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/gjsify/ts-for-gir.git"
-  },
-  "bugs": {
-    "url": "https://github.com/gjsify/ts-for-gir/issues"
-  },
-  "homepage": "https://github.com/gjsify/types/tree/main/gjs#readme"
-}
+    "homepage": "https://github.com/gjsify/types/tree/main/gjs#readme"
+}
+
+

package/system.d.ts

@@ -5,7 +5,7 @@ import type GObject from '@girs/gobject-2.0';
  * 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;
 
@@ -16,7 +16,7 @@ export const version: number;
 
 /**
  * The full path of the executed program.
- * @version Gjs 1.68
+ * @since 1.68
  */
 export const programPath: string | null;
 
@@ -24,7 +24,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[];
 
@@ -39,14 +39,14 @@ export const programArgs: string[];
  * @param o Any Object
  * @returns A hexadecimal string (e.g. `0xb4f170f0`)
  */
-export function addressOf(o: any): string;
+export function addressOf(o: object): string;
 
 /**
  * Return the memory address of any GObject as a 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;
 
@@ -110,7 +110,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
  * {
@@ -145,7 +145,7 @@ export function dumpMemoryInfo(path?: string): void;
  * returns a non-zero error code, then `make` aborts the build.
  * @param code An exit code
  */
-export function exit(code: number): void;
+export function exit(code: number): never;
 
 /**
  * The System module provides common low-level facilities such as access to

package/tsconfig.json

@@ -15,9 +15,10 @@
     "removeComments": false,
     "inlineSourceMap": false,
     "inlineSources": false,
-    "newLine": "LF"
-  },
-  "include": ["./dom.d.ts","./gjs.d.ts"]
+    "newLine": "LF",
+    // Show diagnostics
+    "diagnostics": true  },
+  "include": ["./dom.d.ts","./cairo.d.ts","./gettext.d.ts","./system.d.ts","./console.d.ts","./gjs-ambient.d.ts","./gjs.d.ts"]
 }
 
 

package/typedoc.json

@@ -1,7 +1,9 @@
 {
-    "entryPoints": ["./gjs.d.ts"],
+    "entryPoints": ["./gjs.d.ts","./cairo.d.ts","./gettext.d.ts","./system.d.ts","./dom.d.ts","./console.d.ts"],
     "readme": "./README.md",
     "name": "Gjs",
-    "tsconfig": "./tsconfig.json"
+    "tsconfig": "./tsconfig.json",
+    "skipErrorChecking": true,
+    "highlightLanguages": ["typescript", "javascript", "c", "cpp", "xml", "bash", "json", "css"]
 }