girgen 0.3.8 → 0.3.9

package/README.md

@@ -1,3 +1,210 @@
 # GirGen
 
 GIR Parser and type generator.
+
+## Install
+
+There are pre built binaries for `linux-x64` and `linux-arm64` published on NPM.
+
+```sh
+npm install girgen -D
+./node_modules/.bin/girgen --help
+```
+
+Otherwise you can install from crates.io using `cargo`.
+
+```sh
+cargo install girgen --root .
+./bin/girgen --help
+```
+
+## TypeScript
+
+Generate a standalone package that contains every namespace found in the given
+directories.
+
+```sh
+girgen typescript --help
+```
+
+> [!TIP]
+>
+> You can use the Gnome flatpak SDK to acquire GIR files on systems that don't
+> have them in one place, e.g NixOS or when you are targeting Flatpak.
+>
+> ```sh
+> flatpak run --command=cp --filesystem=home org.gnome.Sdk -r /usr/share/gir-1.0 gir-1.0
+> girgen -d gir-1.0 typescript
+> ```
+
+By default it will generate the package to `.types/gi` which you can then source
+in `tsconfig.json`.
+
+```json
+{
+    "compilerOptions": {
+        "lib": ["es2024"], // don't forget to specify a `lib` to avoid sourcing TypeScript's `dom` lib
+        "skipLibCheck": true, // it's recommended to turn this on
+        "typeRoots": [".types"]
+    }
+}
+```
+
+> [!TIP]
+>
+> Don't forget to gitignore generated files.
+>
+> ```sh
+> echo ".types/gi/" > .gitignore
+> ```
+
+Note that when using `--alias` flag to generate non version imports such as
+`gi://Gtk` make sure to ignore the version you don't need so that it does not
+end up as a union of the two versions.
+
+```sh
+girgen typescript -i Gtk-3.0 --alias
+```
+
+### TypeScript Annotations
+
+GObject has a few additional concepts about class methods and properties that
+cannot be expressed with TypeScript alone. For these girgen generates type only
+fields on classes and interfaces.
+
+We have annotations for:
+
+- signals
+- readable properties
+- writable properties
+- construct-only properties
+
+When implementing a GObject subclass you might want to annotate a subset of
+these or all of these depending on usecase.
+
+Every class that inherits from GObject is going to include a namespace
+containing type declarations where each member is written in `kebab-case`:
+
+```ts
+namespace MyClass {
+    export interface SignalSignatures extends GObject.Object.SignalSignatures {
+        // simple signal
+        "my-signal"(arg: number): void
+        // detailed signals are annotated with the `::{}` suffix
+        "my-detailed-signal::{}"(arg: number): void
+    }
+
+    // ReadableProperties is also used for notify signal annotations
+    export interface ReadableProperties
+        extends GObject.Object.ReadableProperties {
+        // property which has a public getter
+        "my-prop": number
+    }
+
+    export interface WritableProperties
+        extends GObject.Object.WritableProperties {
+        // property which has a public setter
+        "my-prop": number
+    }
+
+    export interface ConstructOnlyProperties
+        extends GObject.Object.ConstructOnlyProperties {
+        // property which can only be set at construction
+        "my-ctor-prop": number
+    }
+}
+```
+
+And the Class will refer to these using special `$` prefixed fields:
+
+> [!IMPORTANT]
+>
+> These fields don't exist at runtime, they are used by other APIs to introspect
+> GObjects.
+
+```ts
+class MyClass extends GObject.Object {
+    declare readonly $signals: MyClass.SignalSignatures
+    declare readonly $readableProperties: MyClass.ReadableProperties
+    declare readonly $writableProperties: MyClass.WritableProperties
+    declare readonly $constructOnlyProperties: MyClass.ConstructOnlyProperties
+
+    static {
+        GObject.registerClass(
+            {
+                Signals: {
+                    "my-signal": {
+                        param_types: [GObject.TYPE_DOUBLE],
+                    },
+                    "my-detailed-signal": {
+                        param_types: [GObject.TYPE_DOUBLE],
+                        flags: GObject.SignalFlags.DETAILED,
+                    },
+                },
+                Properties: {
+                    "my-prop": GObject.ParamSpec.double(
+                        "my-prop",
+                        null,
+                        null,
+                        GObject.ParamFlags.READWRITE,
+                        -GObject.Double.MAX_VALUE,
+                        GObject.Double.MAX_VALUE,
+                    ),
+                    "my-ctor-prop": GObject.ParamSpec.double(
+                        "my-ctor-prop",
+                        null,
+                        null,
+                        GObject.ParamFlags.CONSTRUCT_ONLY,
+                        -GObject.Double.MAX_VALUE,
+                        GObject.Double.MAX_VALUE,
+                    ),
+                },
+            },
+            MyClass,
+        )
+    }
+
+    // GObject.ConstructorProps can be used to infer props from the annotations
+    constructor(props: Partial<GObject.ConstructorProps<MyClass>>) {
+        super(props)
+
+        // note that properties will be annotated as camelCase
+        console.log(props.myProp, props.myCtorProp)
+    }
+}
+```
+
+Methods such as `connect()`, `emit()`, `notify()` will infer from these
+annotations.
+
+```ts
+const instance = new MyClass()
+
+instance.connect("my-signal", (source, arg) => {
+    console.log(arg)
+})
+
+instance.connect("my-detailed-signal::detail", (source, arg) => {
+    console.log(arg)
+})
+
+instance.connect("notify::my-prop", (_, pspec) => {
+    console.log(pspec.name)
+})
+```
+
+Due to how TypeScript `this` type works, you need to annotate `this` or use a
+typecast to correctly infer types within the class.
+
+```ts
+class MyClass {
+    myFn(this: MyClass) {
+        this.emit("my-signal", 0)
+    }
+
+    myFn() {
+        const self = this as MyClass
+        self.emit("my-signal", 0)
+    }
+}
+```

package/bin/girgen.js

@@ -2,6 +2,7 @@
 
 import { arch, platform, argv, exit } from "node:process"
 import { spawnSync } from "node:child_process"
+import { chmod } from "node:fs/promises"
 
 const supportedPlatforms = ["linux-x64", "linux-arm64"]
 const target = `${platform}-${arch}`
@@ -11,6 +12,7 @@ if (!supportedPlatforms.includes(target)) {
 }
 
 const cli = import.meta.resolve(`@girgen/${target}`).replace("file://", "")
+await chmod(cli, 0o755)
 
 const processResult = spawnSync(cli, argv.slice(2), {
     stdio: "inherit",

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "girgen",
-    "version": "0.3.8",
+    "version": "0.3.9",
     "author": "Aylur",
     "license": "MIT",
     "repository": {
@@ -23,8 +23,8 @@
         "@types/node": "latest"
     },
     "optionalDependencies": {
-        "@girgen/linux-x64": "0.3.8",
-        "@girgen/linux-arm64": "0.3.8"
+        "@girgen/linux-x64": "0.3.9",
+        "@girgen/linux-arm64": "0.3.9"
     },
     "files": [
         "bin"