Make examples runnable, validate them with TypeScript and ESLint

Author: amezin

eslint.config.mjs

@@ -10,7 +10,7 @@ import gnome from 'eslint-config-gnome';
 
 export default defineConfig([
     {
-        files: ['*.js', '*.mjs', 'tests/*.js'],
+        files: ['*.js', '*.mjs', 'tests/*.js', 'examples/*.js'],
         plugins: {gnome},
         extends: ['gnome/recommended'],
         rules: {
@@ -42,8 +42,8 @@ export default defineConfig([
         files: [
             'ambient.d.ts',
             'gjs-typelib-installer.js',
-            'tests/test.js',
-            'tests/e2e-test.js',
+            'tests/*.js',
+            'examples/*.js',
         ],
         plugins: {jsdoc, tseslint},
         extends: [
@@ -72,6 +72,7 @@ export default defineConfig([
     {
         files: [
             'tests/*.js',
+            'examples/*.js',
         ],
         plugins: {jsdoc},
         rules: {

examples/gtk4-pkg-name.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env -S gjs -m
+
+// SPDX-FileCopyrightText: 2026 Aleksandr Mezin <mezin.alexander@gmail.com>
+//
+// SPDX-License-Identifier: MIT
+
+import {packages} from '../gjs-typelib-installer.js';
+
+// #region example
+const gtk = packages.Gtk['4.0']().packages;
+
+if (gtk)
+    print(`To install Gtk 4.0 typelib, install the following package(s): ${gtk.join(', ')}`);
+else
+    printerr("Can't find a Gtk 4.0 package for this OS");
+// #endregion example

examples/install-template.js

@@ -0,0 +1,50 @@
+#!/usr/bin/env -S gjs -m
+
+// SPDX-FileCopyrightText: 2026 Aleksandr Mezin <mezin.alexander@gmail.com>
+//
+// SPDX-License-Identifier: MIT
+
+import System from 'system';
+import GLib from 'gi://GLib';
+
+import {require, findTerminalInstallCommand, MissingDependencies} from '../gjs-typelib-installer.js';
+
+// #region example
+/** @import TemplateMod from '@girs/template-1.0' */
+
+try {
+    const {Template} = /** @type {{Template: TemplateMod}} */ (require({Template: '1.0'}));
+
+    const t = Template.Template.new(null);
+    t.parse_string('2 + 2 = {{ 2 + 2 }}');
+    print(t.expand_string(null));
+} catch (ex) {
+    if (!(ex instanceof MissingDependencies))
+        throw ex;
+
+    // For simplicity, we start the installation process immediately here.
+    // But usually it's a good idea to have an "Install" button that the user can click,
+    // or ask for confirmation.
+
+    const installer = await findTerminalInstallCommand();
+
+    if (!installer) {
+        printerr("Can't install packages");
+        System.exit(1);
+    }
+
+    if (ex.packages.size === 0) {
+        printerr("Can't find a package with Template-GLib for this OS");
+        System.exit(1);
+    }
+
+    const argv = installer(ex.packages);
+    const [, pid] = GLib.spawn_async(null, argv, null, GLib.SpawnFlags.DEFAULT, null);
+    GLib.spawn_close_pid(/** @type {GLib.Pid} */ (pid));
+
+    // Note: there's no reliable way to wait for package installation to complete.
+    // Exit with an error, and ask the user to restart the app/enable the extension again.
+    printerr('Please, try again after installing the package');
+    System.exit(1);
+}
+// #endregion example

examples/require-template.js

@@ -0,0 +1,28 @@
+#!/usr/bin/env -S gjs -m
+
+// SPDX-FileCopyrightText: 2026 Aleksandr Mezin <mezin.alexander@gmail.com>
+//
+// SPDX-License-Identifier: MIT
+
+import {require, MissingDependencies} from '../gjs-typelib-installer.js';
+
+// #region example
+/** @import TemplateMod from '@girs/template-1.0' */
+
+try {
+    const {Template} = /** @type {{Template: TemplateMod}} */ (require({Template: '1.0'}));
+
+    const t = Template.Template.new(null);
+    t.parse_string('2 + 2 = {{ 2 + 2 }}');
+    print(t.expand_string(null));
+} catch (ex) {
+    if (!(ex instanceof MissingDependencies))
+        throw ex;
+
+    if (ex.packages.size > 0)
+        printerr(`Please install the packages: ${[...ex.packages].join(', ')}`);
+
+    if (ex.files.size > 0)
+        printerr(`Please install packages that contain the files: ${[...ex.files].join(', ')}`);
+}
+// #endregion example

examples/terminal-hello.js

@@ -0,0 +1,21 @@
+#!/usr/bin/env -S gjs -m
+
+// SPDX-FileCopyrightText: 2026 Aleksandr Mezin <mezin.alexander@gmail.com>
+//
+// SPDX-License-Identifier: MIT
+
+import GLib from 'gi://GLib';
+
+import {findTerminalCommand} from '../gjs-typelib-installer.js';
+
+// #region example
+const terminal = await findTerminalCommand();
+
+if (terminal) {
+    const argv = terminal(['echo', 'Hello, world!']);
+    const [, pid] = GLib.spawn_async(null, argv, null, GLib.SpawnFlags.DEFAULT, null);
+    GLib.spawn_close_pid(/** @type {GLib.Pid} */ (pid));
+} else {
+    printerr('No terminal emulators found');
+}
+// #endregion example

gjs-typelib-installer.js

@@ -123,8 +123,8 @@ function resolveByOsId(filename, distros) {
  * Organized by namespace and version, each entry maps to a resolver function
  * that returns the appropriate package names for the current OS.
  *
- * @example <caption>Get the package name for Gtk 4.0 on the current OS</caption>
- * packages.Gtk['4.0']().packages
+ * @example Get the package name for Gtk 4.0 on the current OS
+ * {@includeCode examples/gtk4-pkg-name.js#example}
  */
 export const packages = {
     Adw: {
@@ -300,20 +300,8 @@ export class MissingDependencies extends Error {
  * {@link MissingDependencies}.
  * @throws {Error} If an unknown library is requested.
  *
- * @example <caption>Import 'gi://Handy?version=1' or ask the user to install packages</caption>
- * try {
- *     const {Handy} = require({Handy: '1'});
- *     // ...
- * } catch (ex) {
- *     if (!(ex instanceof MissingDependencies))
- *         throw ex;
- *
- *     if (ex.packages.size > 0)
- *         printerr(`Please install the packages: ${[...ex.packages]}`);
- *
- *     if (ex.files.size > 0)
- *         printerr(`Please install the packages that contain the files: ${[...ex.files]}`);
- * }
+ * @example Import Template-GLib or ask the user to install packages
+ * {@includeCode examples/require-template.js#example}
  */
 export function require(versions) {
     /** @type {Partial<Record<string, any>>} */
@@ -648,6 +636,9 @@ export async function findInstallCommand(cancellable = null) {
  * @param {Gio.Cancellable|null} cancellable - Optional cancellable for aborting the operation.
  * @returns {Promise<TerminalCommandResolver|null>} A function that generates
  * the command line, or null if no suitable terminal is found.
+ *
+ * @example "Hello, World!" in a new terminal
+ * {@includeCode examples/terminal-hello.js#example}
  */
 // eslint-disable-next-line @typescript-eslint/require-await
 export async function findTerminalCommand(cancellable = null) {
@@ -682,23 +673,8 @@ export async function findTerminalCommand(cancellable = null) {
  * given the list of packages, generates the installation command,
  * wrapped for terminal execution, or null if no terminal or install command is found.
  *
- * @example <caption>Install Gtk 4 package in a separate terminal window</caption>
- * findTerminalInstallCommand().then(installer => {
- *     if (!installer) {
- *         printerr("Can't install packages");
- *         return;
- *     }
- *
- *     const pkgs = packages.Gtk['4.0']().packages;
- *     if (!pkgs) {
- *         printerr("Can't find a Gtk 4.0 package for this OS");
- *         return;
- *     }
- *
- *     const argv = installer(pkgs);
- *     const [, pid] = GLib.spawn_async(null, argv, null, GLib.SpawnFlags.DEFAULT, null);
- *     GLib.spawn_close_pid(pid);
- * });
+ * @example Install Template-GLib package in a separate terminal window
+ * {@includeCode examples/install-template.js#example}
  */
 export async function findTerminalInstallCommand(cancellable = null) {
     cancellable?.set_error_if_cancelled();

package-lock.json

@@ -21,6 +21,7 @@
         "@girs/girepository-2.0": "5.4.0",
         "@girs/girepository-3.0": "5.4.0",
         "@girs/gjs": "5.4.0",
+        "@girs/template-1.0": "5.4.0",
         "eslint": "10.11.0",
         "eslint-config-gnome": "https://github.com/ddterm/eslint-config-gnome/archive/c479d059e8d9ea99c3b53c2ea43abf7fdb05eb51.tar.gz",
         "eslint-plugin-jsdoc": "65.0.0",

package.json

@@ -18,10 +18,10 @@
     ],
   },
   "include": [
-    "eslint.config.mjs",
     "ambient.d.ts",
+    "eslint.config.mjs",
     "gjs-typelib-installer.js",
-    "tests/test.js",
-    "tests/e2e-test.js",
+    "tests/*.js",
+    "examples/*.js",
   ],
 }

tsconfig.json

@@ -9,4 +9,7 @@
     "name": "gjs-typelib-installer",
     "tsconfig": "tsconfig.json",
     "plugin": ["typedoc-plugin-mdn-links"],
+    "jsDocCompatibility": {
+        "exampleTag": false
+    }
 }