fmuellner/troll

Libraries for GNOME JavaScript (GJS)

troll

troll is an implementation of common JavaScript APIs for gjs and some helpers.

See this gjs issue for context.

This is not API stable and no release were made. Use at your own risk. Contributions welcome.

Status

• WebSocket src
• fetch src
  • request
    • method/url
    • headers
    • text body
  • response
    • status/statusText/ok
    • text() / json()
• base64
  • atob src
  • btoa src
• timers builtin gjs 1.72
• console builtin gjs 1.70
• TextDecoder/TextEncoder builtin gjs 1.70

Goals

1. Provide a familiar environment for building GNOME applications
2. Allow application developers to use third party libraries
3. Encourage Shell extension developers to make flatpak apps instead

Tested with

• xmpp.js
• aria2.js

globals

You can register all globals with

import "./troll/globals.js";

// fetch(...)
// new WebSocket(...)
// atob(...)
// btoa(...)

promiseTask(target, method, finish[, ...args])

• target <GObject.object>
• method <string>
• finish <string>
• args an array of arguments to pass to method
• Returns: <Promise>

Run a Gio async operation and return a promise that resolve with the result of finish method or rejects.

Examples

import { promiseTask } from "./troll/util.js";
import Gio from "gi://Gio";

(async () => {
  const file = Gio.File.new_for_path("/tmp/foobar");

  // see https://developer.gnome.org/gio/stable/GFile.html#g-file-replace-readwrite-async
  const stream = await promisetask(file, "readwrite_async", "readwrite_finish");
  log(stream);
})().catch(logError);

gsx

gsx is a small function to write Gtk.

See gsx-demo for setup and instructions with Babel.

You can use it as a jsx pragma with babel, TypeScript or SWC like so:

import Gtk from "gi://Gtk?version=4.0";
import gsx from "./troll/gsx.js";

export default function MyButton() {
  return (
    <Gtk.Button connect-clicked={() => log("clicked")} halign={Gtk.Align.END}>
      <Gtk.Image icon-name="folder-open-symbolic" pixel-size={48} />
    </Gtk.Button>
  );
}

Equivalent without gsx

import Gtk from "gi://Gtk?version=4.0";

export default function MyButton() {
  const image = new Gtk.Image({
    "icon-name": "folder-open-synbolic",
    "pixel-size": 48,
  });

  const button = new Gtk.Button({
    halign: Gtk.Align.END,
  });
  button.connect("signal", () => {
    log("clicked!");
  });

  button.add(image);
}

Usage without a compiler

import Gtk from "gi://Gtk?version=4.0";
import gsx from "./troll/gsx.js";

const { Button, Align, Image } = Gtk;

export default function MyButton() {
  return gsx(
    Button,
    {
      "connect-clicked": () => log("clicked"),
      halign: Align.END,
    },
    gsx(Image, {
      "icon-name": "folder-open-synbolic",
      "pixel-size": 48,
    }),
  );
}