@girs/gjs 3.3.0 → 4.0.0-beta.10

package/gjs.d.ts

@@ -1,13 +1,13 @@
-/*
+/**
  * Type Definitions for Gjs (https://gjs.guide/)
  *
  * These type definitions are automatically generated, do not edit them by hand.
  * If you found a bug fix it in ts-for-gir itself or create a bug report on https://github.com/gjsify/ts-for-gir
  */
-import './ambient.d.ts';
 
 import type GObject from '@girs/gobject-2.0';
 import type GLib from '@girs/glib-2.0';
+
 import gettext from './gettext.js';
 import system from './system.js';
 import cairo from './cairo.js';
@@ -20,73 +20,208 @@ declare namespace package {
      * and all the other have their values derived from them.
      */
     interface PackageInitParams {
-        name: string
-        version: string
-        prefix: string
-        libdir: string
+        /** The base name of the entry point (eg. org.foo.Bar.App) */
+        name: string;
+        /** The version of the package */
+        version: string;
+        /** The prefix of the package */
+        prefix: string;
+        /**
+         * The final datadir and libdir when installed;
+         * usually, these would be prefix + '/share' and
+         * and prefix + '/lib' (or '/lib64')
+         */
+        libdir: string;
+        /**
+         * The final datadir and libdir when installed;
+         * usually, these would be prefix + '/share' and
+         * and prefix + '/lib' (or '/lib64')
+         */
+        datadir?: string;
     }
 
-    export const name: string | undefined
-    export const version: string | undefined
-    export const prefix: string | undefined
-    export const datadir: string | undefined
-    export const libdir: string | undefined
-    export const pkgdatadir: string | undefined
-    export const pkglibdir: string | undefined
-    export const moduledir: string | undefined
-    export const localedir: string | undefined
+    /** 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;
 
-    export function init(params: PackageInitParams): void
-    export function run(module: { main: (argv: string[]) => void }): void
-    /** shortcut to init+run */
-    export function start(params: PackageInitParams): void
-    export function require(libs: Record<string, string>): void
-    export function requireSymbol(lib: string, ver: string, symbol: string): void
-    export function checkSymbol(lib: string, ver: string, symbol: string): void
-    export function initGettext(): void
-    /** @deprecated Use JS string interpolation */
-    export function initFormat(): void
-    export function initSubmodule(module: string): void
+    /**
+     * Initialize directories and global variables. Must be called
+     * before any of other API in Package is used.
+     * `params` must be an object with at least the following keys:
+     *  - name: the package name ($(PACKAGE_NAME) in autotools,
+     *          eg. org.foo.Bar)
+     *  - version: the package version
+     *  - prefix: the installation prefix
+     *
+     * init() will take care to check if the program is running from
+     * the source directory or not, by looking for a 'src' directory.
+     *
+     * At the end, the global variable 'pkg' will contain the
+     * Package module (imports.package). Additionally, the following
+     * module variables will be available:
+     *  - name: the base name of the entry point (eg. org.foo.Bar.App)
+     *  - version: same as in @params
+     *  - prefix: the installation prefix (as passed in @params)
+     *  - datadir, libdir: the final datadir and libdir when installed;
+     *                     usually, these would be prefix + '/share' and
+     *                     and prefix + '/lib' (or '/lib64')
+     *  - pkgdatadir: the directory to look for private data files, such as
+     *                images, stylesheets and UI definitions;
+     *                this will be datadir + name when installed and
+     *                './data' when running from the source tree
+     *  - pkglibdir: the directory to look for private typelibs and C
+     *               libraries;
+     *               this will be libdir + name when installed and
+     *               './lib' when running from the source tree
+     *  - moduledir: the directory to look for JS modules;
+     *               this will be pkglibdir when installed and
+     *               './src' when running from the source tree
+     *  - localedir: the directory containing gettext translation files;
+     *               this will be datadir + '/locale' when installed
+     *               and './po' in the source tree
+     *
+     * All paths are absolute and will not end with '/'.
+     *
+     * As a side effect, init() calls GLib.set_prgname().
+     *
+     * @param {object} params package parameters
+     */
+    export function init(params: PackageInitParams): void;
+    /**
+     * This is the function to use if you want to have multiple
+     * entry points in one package.
+     * You must define a main(ARGV) function inside the passed
+     * in module, and then the launcher would be
+     *
+     * imports.package.init(...);
+     * imports.package.run(imports.entrypoint);
+     *
+     * @param module the module to run
+     * @returns the exit code of the module's main() function
+     */
+    export function run(module: { main: (argv: string[]) => void }): number | undefined;
+    /**
+     * This is a convenience function if your package has a
+     * single entry point.
+     * You must define a main(ARGV) function inside a main.js
+     * module in moduledir.
+     *
+     * @param params see init()
+     */
+    export function start(params: PackageInitParams): void;
+    /**
+     * Mark a dependency on a specific version of one or more
+     * external GI typelibs.
+     * `libs` must be an object whose keys are a typelib name,
+     * and values are the respective version. The empty string
+     * indicates any version.
+     * @param deps The external dependencies to import
+     */
+    export function require(deps: Record<string, string>): void;
+    /**
+     * As checkSymbol(), but exit with an error if the
+     * dependency cannot be satisfied.
+     *
+     * @param lib an external dependency to import
+     * @param ver version of the dependency
+     * @param symbol symbol to check for
+     */
+    export function requireSymbol(lib: string, ver?: string, symbol?: string): void;
+    /**
+     * Check whether an external GI typelib can be imported
+     * and provides @symbol.
+     *
+     * Symbols may refer to
+     *  - global functions         ('main_quit')
+     *  - classes                  ('Window')
+     *  - class / instance methods ('IconTheme.get_default' / 'IconTheme.has_icon')
+     *  - GObject properties       ('Window.default_height')
+     *
+     * @param lib an external dependency to import
+     * @param ver version of the dependency
+     * @param symbol symbol to check for
+     * @returns true if `lib` can be imported and provides `symbol`, false
+     * otherwise
+     */
+    export function checkSymbol(lib: string, ver: string, symbol: string): boolean;
+    /**
+     * Initialize `gettext`.
+     * After calling this method `globalThis._`, `globalThis.C_` and `globalThis.N_` will be available.
+     */
+    export function initGettext(): void;
+    /**
+     * @deprecated Use JS string interpolation
+     */
+    export function initFormat(): void;
+    /**
+     * As checkSymbol(), but exit with an error if the
+     * dependency cannot be satisfied.
+     *
+     * @param lib an external dependency to import
+     * @param ver version of the dependency
+     * @param symbol symbol to check for
+     */
+    export function initSubmodule(lib: string, ver?: string, symbol?: string): void;
+    /**
+     * Load and register a GResource named @name. @name is optional and defaults to ${package-name}
+     * @param name The name of the GResource to load
+     */
+    export function loadResource(name?: string): void;
 }
 
 declare namespace byteArray {
     export class ByteArray {
-        static get(target: any, property: string, receiver: any): any
-        static set(target: any, property: string, value: any, receiver: any): boolean
+        static get(target: any, property: string, receiver: any): any;
+        static set(target: any, property: string, value: any, receiver: any): boolean;
 
-        length: number
-        protected _array: Uint8Array
+        length: number;
+        protected _array: Uint8Array;
 
-        constructor(x: Uint8Array | number)
-        toString(encoding?: TextDecoderEncoding): string
-        fromString(input: string, encoding?: TextDecoderEncoding): ByteArray
-        toGBytes(): GLib.Bytes
+        constructor(x: Uint8Array | number);
+        toString(encoding?: TextDecoderEncoding): string;
+        fromString(input: string, encoding?: TextDecoderEncoding): ByteArray;
+        toGBytes(): GLib.Bytes;
     }
 
     /** @deprecated Use {@link TextEncoder.encode} instead */
-    export function fromString(input: string, encoding?: TextDecoderEncoding): Uint8Array
+    export function fromString(input: string, encoding?: TextDecoderEncoding): Uint8Array;
 
     /** @deprecated Use {@link GLib.Bytes.toArray} instead */
-    export function fromGBytes(input: GLib.Bytes): Uint8Array
+    export function fromGBytes(input: GLib.Bytes): Uint8Array;
 
     /** @deprecated Use {@link TextDecoder.decode} instead */
-    export function toString(x: Uint8Array, encoding?: TextDecoderEncoding): string
+    export function toString(x: Uint8Array, encoding?: TextDecoderEncoding): string;
 
     /** @deprecated Use {@link GLib.Bytes new GLib.Bytes() } instead */
-    export function toGBytes(x: Uint8Array): GLib.Bytes
+    export function toGBytes(x: Uint8Array): GLib.Bytes;
 
     /** @deprecated Use {@link ByteArray new ByteArray()} instead */
-    export function fromArray(array: Iterable<number>): ByteArray
+    export function fromArray(array: Iterable<number>): ByteArray;
 }
 
 declare namespace lang {
     // TODO: There is a lot more in Lang
-    export function Class(props: any): void
+    export function Class(props: any): void;
 }
 
 declare namespace format {
-    export function vprintf(str: string, args: string[]): string
-    export function printf(fmt: string, ...args: any[]): void
+    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
@@ -99,19 +234,19 @@ declare namespace format {
      * field width, e.g. "%5s".format("foo"). Unless the width is prefixed
      * with '0', the formatted string will be padded with spaces.
      */
-    export function format(fmt: string, ...args: any[]): string
+    export function format(fmt: string, ...args: any[]): string;
 }
 
 declare namespace mainloop {
-    export function quit(name: string): void
-    export function idle_source(handler: any, priority?: number): any
-    export function idle_add(handler: any, priority?: number): any
-    export function timeout_source(timeout: any, handler: any, priority?: number): any
-    export function timeout_seconds_source(timeout: any, handler: any, priority?: number): any
-    export function timeout_add(timeout: any, handler: any, priority?: number): any
-    export function timeout_add_seconds(timeout: any, handler: any, priority?: number): any
-    export function source_remove(id: any): any
-    export function run(name: string): void
+    export function quit(name: string): void;
+    export function idle_source(handler: any, priority?: number): any;
+    export function idle_add(handler: any, priority?: number): any;
+    export function timeout_source(timeout: any, handler: any, priority?: number): any;
+    export function timeout_seconds_source(timeout: any, handler: any, priority?: number): any;
+    export function timeout_add(timeout: any, handler: any, priority?: number): any;
+    export function timeout_add_seconds(timeout: any, handler: any, priority?: number): any;
+    export function source_remove(id: any): any;
+    export function run(name: string): void;
 }
 
 /**
@@ -121,15 +256,15 @@ declare namespace mainloop {
  * @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");
  * ```
@@ -138,13 +273,13 @@ export interface SignalMethods {
     /**
      * Connects a callback to a signal for an object. Pass the returned ID to
      * `disconnect()` 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
@@ -152,7 +287,7 @@ export interface SignalMethods {
     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.
@@ -168,7 +303,7 @@ export interface SignalMethods {
     /**
      * Disconnects all signal handlers for an object.
      */
-    disconnectAll(): void
+    disconnectAll(): void;
     /**
      * Checks if a handler ID is connected.
      * @param id The ID of the handler to be disconnected
@@ -182,7 +317,6 @@ declare namespace signals {
 }
 
 declare global {
-
     // https://gitlab.gnome.org/GNOME/gjs/-/blob/1.73.2/modules/esm/_encoding/encodingMap.js#L7-232
     type TextDecoderEncoding =
         | 'unicode-1-1-utf-8'
@@ -404,56 +538,72 @@ declare global {
         | 'unicode'
         | 'unicodefeff'
         | 'utf-16'
-        | 'utf-16le'
+        | 'utf-16le';
 
     interface GjsGiImports {
         // Will be extended by the import of more gir types
         versions: {
-            [namespace: string]: string
-        }
+            [namespace: string]: string;
+        };
     }
-    
+
     interface GjsImports {
-        gi: GjsGiImports
-        lang: typeof lang
-        system: typeof system
-        signals: typeof signals
-        package: typeof package
-        mainloop: typeof mainloop
-        searchPath: string[]
-        gettext: typeof gettext
-        byteArray: typeof byteArray
-        format: typeof format
-        cairo: typeof cairo
+        gi: GjsGiImports;
+        lang: typeof lang;
+        system: typeof system;
+        signals: typeof signals;
+        package: typeof package;
+        mainloop: typeof mainloop;
+        searchPath: string[];
+        gettext: typeof gettext;
+        byteArray: typeof byteArray;
+        format: typeof format;
+        cairo: typeof cairo;
     }
 
-    function print(...args: any[]): void
-    function printerr(...args: any[]): void
-    function log(message: any): void
-    function logError(exception: object, message?: any): void
-    function logError(message?: any): void
+    // Overwrites, see https://gitlab.gnome.org/GNOME/gjs/-/blob/master/modules/script/package.js
+    /**
+     * Run `pkg.initGettext()` before using this.
+     * See {@link gettext.gettext}
+     */
+    const _: undefined | typeof gettext.gettext;
+    /**
+     * Run `pkg.initGettext()` before using this.
+     * See {@link gettext.pgettext}
+     */
+    const C_: undefined | typeof gettext.pgettext;
+    /**
+     * Run `pkg.initGettext()` before using this.
+     * Currently not implemented.
+     */
+    const N_: undefined | ((x: string) => string);
+
+    function print(...args: any[]): void;
+    function printerr(...args: any[]): void;
+    function log(obj: object, others?: object[]): void;
+    function log(msg: string, substitutions?: any[]): void;
+    function logError(exception: object, message?: any): void;
+    function logError(message?: any): void;
 
-    const pkg: typeof package
+    const pkg: typeof package;
 
     interface BooleanConstructor {
-        $gtype: GObject.GType<boolean>
+        $gtype: GObject.GType<boolean>;
     }
 
     interface NumberConstructor {
-        $gtype: GObject.GType<number>
+        $gtype: GObject.GType<number>;
     }
 
     interface StringConstructor {
-        $gtype: GObject.GType<string>
+        $gtype: GObject.GType<string>;
     }
 
-    const imports: GjsImports
+    const imports: GjsImports;
 
-    const ARGV: string[]
+    const ARGV: string[];
 }
 
-declare const _imports: GjsImports
-export default _imports
-export { _imports as imports }
-
-
+declare const _imports: GjsImports;
+export default _imports;
+export { _imports as imports };

package/gjs.js

@@ -2,5 +2,5 @@ const imports = globalThis.imports || {};
 
 export { imports }
 export default imports;
-  
+
 

package/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Type Definitions for Gjs (https://gjs.guide/)
+ *
+ * These type definitions are automatically generated, do not edit them by hand.
+ * If you found a bug fix it in `ts-for-gir` or create a bug report on https://github.com/gjsify/ts-for-gir
+ *
+ * This template is used to generate the index.d.ts file of each GIR module like Gtk-4.0, GObject-2.0, ...
+ */
+
+import './gjs-ambient.d.ts';
+
+import gjs from './gjs.js';
+export default gjs;

package/index.js

@@ -0,0 +1,5 @@
+
+// @ts-expect-error
+import gjs from './gjs.js';
+export default gjs;
+

package/package.json

@@ -1,68 +1,54 @@
 {
   "name": "@girs/gjs",
-  "version": "3.3.0",
+  "version": "4.0.0-beta.10",
   "description": "GJS TypeScript type definitions for Gjs",
   "type": "module",
   "module": "gjs.js",
   "main": "gjs.js",
   "exports": {
     "./ambient": {
-      "types": "./ambient.d.ts",
-      "default": "./ambient.js"
+      "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": {
-      "import": {
-        "types": "./gettext.d.ts",
-        "default": "./gettext.js"
-      },
-      "require": {
-        "types": "./gettext.d.cts",
-        "default": "./gettext.cjs"
-      }
+      "types": "./gettext.d.ts",
+      "import": "./gettext.js",
+      "default": "./gettext.js"
     },
     "./system": {
-      "import": {
-        "types": "./system.d.ts",
-        "default": "./system.js"
-      },
-      "require": {
-        "types": "./system.d.cts",
-        "default": "./system.cjs"
-      }
+      "types": "./system.d.ts",
+      "import": "./system.js",
+      "default": "./system.js"
     },
     "./cairo": {
-      "import": {
-        "types": "./cairo.d.ts",
-        "default": "./cairo.js"
-      },
-      "require": {
-        "types": "./cairo.d.cts",
-        "default": "./cairo.cjs"
-      }
+      "types": "./cairo.d.ts",
+      "import": "./cairo.js",
+      "default": "./cairo.js"
     },
-    "./dom": {
-      "types": "./dom.d.ts",
-      "default": "./dom.js"
+    "./gjs": {
+      "types": "./gjs.d.ts",
+      "import": "./gjs.js",
+      "default": "./gjs.js"
     },
     ".": {
-      "import": {
-        "types": "./gjs.d.ts",
-        "default": "./gjs.js"
-      },
-      "require": {
-        "types": "./gjs.d.cts",
-        "default": "./gjs.cjs"
-      }
+      "types": "./index.d.ts",
+      "import": "./index.js",
+      "default": "./index.js"
     }
   },
   "scripts": {
-    "test": "yarn test:esm && yarn test:cjs",
-    "test:esm": "NODE_OPTIONS=--max_old_space_size=9216 tsc --noEmit gjs.d.ts",
-    "test:cjs": "NODE_OPTIONS=--max_old_space_size=9216 tsc --noEmit gjs.d.cts"
+    "test": "tsc --project tsconfig.json"
   },
   "dependencies": {
-    "@girs/glib-2.0": "^2.78.0-3.3.0",
-    "@girs/gobject-2.0": "^2.78.0-3.3.0"
+    "@girs/gio-2.0": "^2.80.2-4.0.0-beta.10",
+    "@girs/glib-2.0": "^2.80.2-4.0.0-beta.10",
+    "@girs/gobject-2.0": "^2.80.2-4.0.0-beta.10"
   },
   "devDependencies": {
     "typescript": "*"