@girs/gjs 3.2.7 → 3.2.8

package/README.md

@@ -4,7 +4,7 @@
 ![version](https://img.shields.io/npm/v/@girs/gjs)
 ![downloads/week](https://img.shields.io/npm/dw/@girs/gjs)
 
-GJS TypeScript type definitions for Gjs using [ts-for-gir](https://github.com/gjsify/ts-for-gir) v3.2.7.
+GJS TypeScript type definitions for Gjs using [ts-for-gir](https://github.com/gjsify/ts-for-gir) v3.2.8.
 
 [GJS](https://gitlab.gnome.org/GNOME/gjs) is a JavaScript runtime for the GNOME ecosystem. Using GJS and the type definitions in this NPM package, you can build GTK applications in JavaScript or TypeScript with type checking, better autocompletion and inline documentations.
 

package/ambient.js

@@ -0,0 +1,3 @@
+export {};
+
+

package/dom.js

@@ -0,0 +1,3 @@
+export {};
+
+

package/package.json

@@ -1,12 +1,15 @@
 {
   "name": "@girs/gjs",
-  "version": "3.2.7",
+  "version": "3.2.8",
   "description": "GJS TypeScript type definitions for Gjs",
   "type": "module",
   "module": "gjs.js",
   "main": "gjs.js",
   "exports": {
-    "./ambient": "./ambient.d.ts",
+    "./ambient": {
+      "types": "./ambient.d.ts",
+      "default": "./ambient.js"
+    },
     "./gettext": {
       "import": {
         "types": "./gettext.d.ts",
@@ -37,7 +40,10 @@
         "default": "./cairo.cjs"
       }
     },
-    "./dom": "./dom.d.ts",
+    "./dom": {
+      "types": "./dom.d.ts",
+      "default": "./dom.js"
+    },
     ".": {
       "import": {
         "types": "./gjs.d.ts",
@@ -55,8 +61,8 @@
     "test:cjs": "NODE_OPTIONS=--max_old_space_size=9216 tsc --noEmit gjs.d.cts"
   },
   "dependencies": {
-    "@girs/glib-2.0": "^2.78.0-3.2.7",
-    "@girs/gobject-2.0": "^2.78.0-3.2.7"
+    "@girs/glib-2.0": "^2.77.0-3.2.8",
+    "@girs/gobject-2.0": "^2.77.0-3.2.8"
   },
   "devDependencies": {
     "typescript": "*"
@@ -73,7 +79,7 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/gjsify/types.git"
+    "url": "git+https://github.com/gjsify/ts-for-gir.git"
   },
   "bugs": {
     "url": "https://github.com/gjsify/ts-for-gir/issues"

package/system.d.cts

@@ -1,31 +1,174 @@
 import type GObject from '@girs/gobject-2.0';
 
+/**
+ * This property contains the name of the script as it was invoked from the command
+ * 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
+ */
 export const programInvocationName: string
+
+/**
+ * This property contains version information about GJS.
+ */
 export const version: number
+
+/**
+ * The full path of the executed program.
+ * @version Gjs 1.68
+ */
 export const programPath: string | null
-/** Equal to ARGV */
+
+/**
+ * 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
+ */
 export const programArgs: string[]
-export function exit(code: number): void
-export function addressOfGObject(o: GObject.Object): object
-export function addressOf(o: any): object
+
+/**
+ * Return the memory address of any object as a string.
+ * This is the address of memory being managed by the JavaScript engine, which may
+ * represent a wrapper around memory elsewhere.
+ * **Caution**, don't use this as a unique identifier!
+ * JavaScript's garbage collector can move objects around in memory, or
+ * deduplicate identical objects, so this value may change during the execution
+ * of a program.
+ * @param o Any Object
+ * @returns A hexadecimal string (e.g. `0xb4f170f0`)
+ */
+export function addressOf(o: any): 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
+ */
+export function addressOfGObject(o: GObject.Object): string
+
+/**
+ * Inserts a breakpoint instruction into the code.
+ * **Warning**: Using this function in code run outside of GDB will abort the process.
+ * With `System.breakpoint()` calls in your code, a GJS program can be debugged by
+ * running it in GDB:
+ * ```bash
+ * gdb --args gjs script.js
+ * ```
+ * Once GDB has started, you can start the program with run. When the debugger
+ * hits a breakpoint it will pause execution of the process and return to the
+ * prompt. You can then use the standard `backtrace` command to print a C++ stack
+ * trace, or use `call gjs_dumpstack()` to print a JavaScript stack trace:
+ * ```bash
+ * (gdb) run
+ * tarting program: /usr/bin/gjs -m script.js
+ * ...
+ * Thread 1 "gjs" received signal SIGTRAP, Trace/breakpoint trap.
+ * (gdb) call gjs_dumpstack()
+ * == Stack trace for context 0x5555555b7180 ==
+ * #0   555555640548 i   file:///path/to/script.js:4 (394b8c3cc060 @ 12)
+ * #1   5555556404c8 i   file:///path/to/script.js:7 (394b8c3cc0b0 @ 6)
+ * #2   7fffffffd3a0 b   self-hosted:2408 (394b8c3a9650 @ 753)
+ * #3   5555556403e8 i   self-hosted:2355 (394b8c3a9600 @ 375)
+ * (gdb)
+ * ```
+ * To continue executing the program, you can use the `continue` (or `cont`) to
+ * resume the process and debug further.
+ * Remember that if you run the program outside of GDB, it will abort at the
+ * breakpoint, so make sure to remove any calls to `System.breakpoint()` when
+ * you're done debugging.
+ */
+export function breakpoint(): void
+
+/**
+ * Clears the timezone cache.
+ * This is a workaround for SpiderMonkey Bug [#1004706](https://bugzilla.mozilla.org/show_bug.cgi?id=1004706).
+ */
+export function clearDateCaches(): void
+
 /** Runs the garbage collector */
 export function gc(): void
+
+/**
+ * Return the reference count of any GObject-derived type. When an object's
+ * reference count is zero, it is cleaned up and erased from memory.
+ * @param o A {@link GObject.Object}
+ */
 export function refcount(o: GObject.Object): number
-export function dumpHeap(path: string): void
-export function dumpMemoryInfo(path: string): void
+/**
+ * See also: The [heapgraph](https://gitlab.gnome.org/GNOME/gjs/blob/HEAD/tools/heapgraph.md) utility in the GJS repository.
+ * Dump a representation of internal heap memory. If `path` is not given, GJS will
+ * write the contents to `stdout`.
+ * @param path  Optional file path
+ */
+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
+ * @example Output:
+ * ```json
+ * {
+ *   "gcBytes": 794624,
+ *   "gcMaxBytes": 4294967295,
+ *   "mallocBytes": 224459,
+ *   "gcIsHighFrequencyMode": true,
+ *   "gcNumber": 1,
+ *   "majorGCCount": 1,
+ *   "minorGCCount": 1,
+ *   "sliceCount": 1,
+ *   "zone": {
+ *     "gcBytes": 323584,
+ *     "gcTriggerBytes": 42467328,
+ *     "gcAllocTrigger": 36097228.8,
+ *     "mallocBytes": 120432,
+ *     "mallocTriggerBytes": 59768832,
+ *     "gcNumber": 1
+ *   }
+ * }
+ * ```
+ * 
+ */
+export function dumpMemoryInfo(path?: string): void
+
+/**
+ * This works the same as C's exit() function; exits the program, passing a
+ * certain error code to the shell. The shell expects the error code to be zero if
+ * there was no error, or non-zero (any value you please) to indicate an error.
+ * 
+ * This value is used by other tools such as `make`; if `make` calls a program that
+ * returns a non-zero error code, then `make` aborts the build.
+ * @param code An exit code
+ */
+export function exit(code: number): void
 
+/**
+ * The System module provides common low-level facilities such as access to
+ * process arguments and exit(), as well as a number of useful functions and
+ * properties for debugging.
+ * 
+ * Note that the majority of the functions and properties in this module should not
+ * be used in normal operation of a GJS application.
+ */
 declare const System: {
     programInvocationName: typeof programInvocationName,
     version: typeof version,
     programPath: typeof programPath,
     programArgs: typeof programArgs,
-    exit: typeof exit,
-    addressOfGObject: typeof addressOfGObject,
     addressOf: typeof addressOf,
+    addressOfGObject: typeof addressOfGObject,
+    breakpoint: typeof breakpoint,
+    clearDateCaches: typeof clearDateCaches,
     gc: typeof gc,
     refcount: typeof refcount,
     dumpHeap: typeof dumpHeap,
     dumpMemoryInfo: typeof dumpMemoryInfo,
+    exit: typeof exit,
 }
 
 export default System

package/system.d.ts

@@ -1,31 +1,174 @@
 import type GObject from '@girs/gobject-2.0';
 
+/**
+ * This property contains the name of the script as it was invoked from the command
+ * 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
+ */
 export const programInvocationName: string
+
+/**
+ * This property contains version information about GJS.
+ */
 export const version: number
+
+/**
+ * The full path of the executed program.
+ * @version Gjs 1.68
+ */
 export const programPath: string | null
-/** Equal to ARGV */
+
+/**
+ * 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
+ */
 export const programArgs: string[]
-export function exit(code: number): void
-export function addressOfGObject(o: GObject.Object): object
-export function addressOf(o: any): object
+
+/**
+ * Return the memory address of any object as a string.
+ * This is the address of memory being managed by the JavaScript engine, which may
+ * represent a wrapper around memory elsewhere.
+ * **Caution**, don't use this as a unique identifier!
+ * JavaScript's garbage collector can move objects around in memory, or
+ * deduplicate identical objects, so this value may change during the execution
+ * of a program.
+ * @param o Any Object
+ * @returns A hexadecimal string (e.g. `0xb4f170f0`)
+ */
+export function addressOf(o: any): 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
+ */
+export function addressOfGObject(o: GObject.Object): string
+
+/**
+ * Inserts a breakpoint instruction into the code.
+ * **Warning**: Using this function in code run outside of GDB will abort the process.
+ * With `System.breakpoint()` calls in your code, a GJS program can be debugged by
+ * running it in GDB:
+ * ```bash
+ * gdb --args gjs script.js
+ * ```
+ * Once GDB has started, you can start the program with run. When the debugger
+ * hits a breakpoint it will pause execution of the process and return to the
+ * prompt. You can then use the standard `backtrace` command to print a C++ stack
+ * trace, or use `call gjs_dumpstack()` to print a JavaScript stack trace:
+ * ```bash
+ * (gdb) run
+ * tarting program: /usr/bin/gjs -m script.js
+ * ...
+ * Thread 1 "gjs" received signal SIGTRAP, Trace/breakpoint trap.
+ * (gdb) call gjs_dumpstack()
+ * == Stack trace for context 0x5555555b7180 ==
+ * #0   555555640548 i   file:///path/to/script.js:4 (394b8c3cc060 @ 12)
+ * #1   5555556404c8 i   file:///path/to/script.js:7 (394b8c3cc0b0 @ 6)
+ * #2   7fffffffd3a0 b   self-hosted:2408 (394b8c3a9650 @ 753)
+ * #3   5555556403e8 i   self-hosted:2355 (394b8c3a9600 @ 375)
+ * (gdb)
+ * ```
+ * To continue executing the program, you can use the `continue` (or `cont`) to
+ * resume the process and debug further.
+ * Remember that if you run the program outside of GDB, it will abort at the
+ * breakpoint, so make sure to remove any calls to `System.breakpoint()` when
+ * you're done debugging.
+ */
+export function breakpoint(): void
+
+/**
+ * Clears the timezone cache.
+ * This is a workaround for SpiderMonkey Bug [#1004706](https://bugzilla.mozilla.org/show_bug.cgi?id=1004706).
+ */
+export function clearDateCaches(): void
+
 /** Runs the garbage collector */
 export function gc(): void
+
+/**
+ * Return the reference count of any GObject-derived type. When an object's
+ * reference count is zero, it is cleaned up and erased from memory.
+ * @param o A {@link GObject.Object}
+ */
 export function refcount(o: GObject.Object): number
-export function dumpHeap(path: string): void
-export function dumpMemoryInfo(path: string): void
+/**
+ * See also: The [heapgraph](https://gitlab.gnome.org/GNOME/gjs/blob/HEAD/tools/heapgraph.md) utility in the GJS repository.
+ * Dump a representation of internal heap memory. If `path` is not given, GJS will
+ * write the contents to `stdout`.
+ * @param path  Optional file path
+ */
+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
+ * @example Output:
+ * ```json
+ * {
+ *   "gcBytes": 794624,
+ *   "gcMaxBytes": 4294967295,
+ *   "mallocBytes": 224459,
+ *   "gcIsHighFrequencyMode": true,
+ *   "gcNumber": 1,
+ *   "majorGCCount": 1,
+ *   "minorGCCount": 1,
+ *   "sliceCount": 1,
+ *   "zone": {
+ *     "gcBytes": 323584,
+ *     "gcTriggerBytes": 42467328,
+ *     "gcAllocTrigger": 36097228.8,
+ *     "mallocBytes": 120432,
+ *     "mallocTriggerBytes": 59768832,
+ *     "gcNumber": 1
+ *   }
+ * }
+ * ```
+ * 
+ */
+export function dumpMemoryInfo(path?: string): void
+
+/**
+ * This works the same as C's exit() function; exits the program, passing a
+ * certain error code to the shell. The shell expects the error code to be zero if
+ * there was no error, or non-zero (any value you please) to indicate an error.
+ * 
+ * This value is used by other tools such as `make`; if `make` calls a program that
+ * returns a non-zero error code, then `make` aborts the build.
+ * @param code An exit code
+ */
+export function exit(code: number): void
 
+/**
+ * The System module provides common low-level facilities such as access to
+ * process arguments and exit(), as well as a number of useful functions and
+ * properties for debugging.
+ * 
+ * Note that the majority of the functions and properties in this module should not
+ * be used in normal operation of a GJS application.
+ */
 declare const System: {
     programInvocationName: typeof programInvocationName,
     version: typeof version,
     programPath: typeof programPath,
     programArgs: typeof programArgs,
-    exit: typeof exit,
-    addressOfGObject: typeof addressOfGObject,
     addressOf: typeof addressOf,
+    addressOfGObject: typeof addressOfGObject,
+    breakpoint: typeof breakpoint,
+    clearDateCaches: typeof clearDateCaches,
     gc: typeof gc,
     refcount: typeof refcount,
     dumpHeap: typeof dumpHeap,
     dumpMemoryInfo: typeof dumpMemoryInfo,
+    exit: typeof exit,
 }
 
 export default System