gnim 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Aylur
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,44 @@
+# Gnim
+
+Library which brings JSX and reactivity to GNOME JavaScript.
+
+If you are not already familiar with GJS and GObject, you should read
+[gjs.guide](https://gjs.guide/) first.
+
+This library provides:
+
+- [JSX and reactivity](https://aylur.github.io/gnim/jsx) for both Gtk
+  Applications and Gnome extensions
+- [GObject decorators](https://aylur.github.io/gnim/gobject) for a convenient
+  and type safe way for subclassing GObjects
+- [DBus decorators](https://aylur.github.io/gnim/dbus) for a convenient and type
+  safe way for implementing DBus services and proxies.
+
+## Obligatory Counter Example
+
+```tsx
+function Counter() {
+  const [counter, setCounter] = createState(0)
+
+  function increment() {
+    setCounter((v) => v + 1)
+  }
+
+  return (
+    <Gtk.Box spacing={8}>
+      <Gtk.Label label={counter((c) => c.toString())} />
+      <Gtk.Button onClicked={increment}>Increment</Gtk.Button>
+    </Gtk.Box>
+  )
+}
+```
+
+## Example apps using Gnim
+
+- [icon-theme-browser](https://github.com/Aylur/icon-theme-browser)
+
+## Credits
+
+- [JU12000](https://github.com/JU12000) for suggesting the name Gnim
+- [Azazel-Woodwind](https://github.com/Azazel-Woodwind) for a lot of early
+  testing

package/dist/dbus.d.ts

@@ -0,0 +1,141 @@
+/**
+ * A {@link Service} currently only allows interfacing with a single interface of a remote object.
+ * In the future I want to come up with an API to be able to create Service objects for multiple
+ * interfaces of an object at the same time. Example usage would be for example combining
+ * "org.mpris.MediaPlayer2" and "org.mpris.MediaPlayer2.Player" into a single object.
+ */
+import Gio from "gi://Gio";
+import GLib from "gi://GLib";
+import GObject from "gi://GObject";
+declare const info: unique symbol;
+declare const internals: unique symbol;
+declare const remoteMethod: unique symbol;
+declare const remoteMethodAsync: unique symbol;
+declare const remotePropertySet: unique symbol;
+/**
+ * Base type for DBus services and proxies. Interface name is set with
+ * the {@link iface} decorator which also register it as a GObject type.
+ */
+export declare class Service extends GObject.Object {
+    #private;
+    static [info]?: Gio.DBusInterfaceInfo;
+    [internals]: {
+        dbusObject?: Gio.DBusExportedObject;
+        proxy?: Gio.DBusProxy;
+        priv: Record<string | symbol, unknown>;
+        onStop: Set<() => void>;
+    };
+    constructor();
+    notify(propertyName: Extract<keyof this, string> | (string & {})): void;
+    emit(name: string, ...params: unknown[]): void;
+    serve({ busType, name, objectPath, flags, timeout, }?: {
+        busType?: Gio.BusType;
+        name?: string;
+        objectPath?: string;
+        flags?: Gio.BusNameOwnerFlags;
+        timeout?: number;
+    }): Promise<this>;
+    [remoteMethod](methodName: string, args: unknown[]): GLib.Variant;
+    [remoteMethodAsync](methodName: string, args: unknown[]): Promise<GLib.Variant>;
+    [remotePropertySet](name: string, value: unknown): void;
+    proxy({ bus, name, objectPath, flags, timeout, }?: {
+        bus?: Gio.DBusConnection;
+        name?: string;
+        objectPath?: string;
+        flags?: Gio.DBusProxyFlags;
+        timeout?: number;
+    }): Promise<this>;
+    stop(): void;
+}
+/**
+ * Registers a {@link Service} as a dbus interface.
+ *
+ * @param name Interface name of the object. For example "org.gnome.Shell.SearchProvider2"
+ * @param gobjectMetaInfo optional properties to pass to {@link GObject.registerClass}
+ */
+export declare function iface(name: string, gobjectMetaInfo?: GObject.MetaInfo<never, Array<{
+    $gtype: GObject.GType;
+}>, never>): (cls: {
+    new (...args: any[]): Service;
+}, ctx: ClassDecoratorContext) => void;
+type DBusType = string | {
+    type: string;
+    name: string;
+};
+type InferVariantTuple<NestedVariant extends string> = NestedVariant extends string ? Array<any> : never;
+/**
+ * Infer the runtime JavaScript type of a Variant type
+ */
+export type InferVariantType<T extends string> = T extends "v" ? Variant<any> : T extends "b" ? boolean : T extends "y" | "n" | "q" | "i" | "u" | "x" | "t" | "h" | "d" ? number : T extends "s" | "g" ? string : T extends "o" ? `/${string}` : T extends `a{${infer K}${infer S}}` ? S extends string ? K extends string ? Record<Extract<InferVariantType<K>, string | number>, InferVariantType<S>> : never : never : T extends `a${infer S}` ? S extends string ? Array<InferVariantType<S>> : never : T extends `(${infer S})` ? S extends string ? InferVariantTuple<S> : never : never;
+type InferVariantTypes<T extends Array<DBusType>> = {
+    [K in keyof T]: T[K] extends string ? InferVariantType<T[K]> : T[K] extends {
+        type: infer S;
+    } ? S extends string ? InferVariantType<S> : never : unknown;
+};
+/**
+ * Registers a method.
+ * You should prefer using {@link methodAsync} when proxying, due to IO blocking.
+ * Note that this is functionally the same as {@link methodAsync} on exported objects.
+ * ```
+ */
+export declare function method<const InArgs extends Array<DBusType>, const OutArgs extends Array<DBusType>>(inArgs: InArgs, outArgs: OutArgs): (method: (this: Service, ...args: InferVariantTypes<InArgs>) => InferVariantTypes<OutArgs>, ctx: ClassMethodDecoratorContext<Service, typeof method>) => void;
+/**
+ * Registers a method.
+ * You should prefer using {@link methodAsync} when proxying, due to IO blocking.
+ * Note that this is functionally the same as {@link methodAsync} on exported objects.
+ * ```
+ */
+export declare function method<const InArgs extends Array<DBusType>>(...inArgs: InArgs): (method: (this: Service, ...args: InferVariantTypes<InArgs>) => void, ctx: ClassMethodDecoratorContext<Service, typeof method>) => void;
+/**
+ * Registers a method.
+ * You should prefer using this over {@link method} when proxying, since this does not block IO.
+ * Note that this is functionally the same as {@link method} on exported objects.
+ * ```
+ */
+export declare function methodAsync<const InArgs extends Array<DBusType>, const OutArgs extends Array<DBusType>>(inArgs: InArgs, outArgs: OutArgs): (method: (this: Service, ...args: InferVariantTypes<InArgs>) => Promise<InferVariantTypes<OutArgs>>, ctx: ClassMethodDecoratorContext<Service, typeof method>) => void;
+/**
+ * Registers a method.
+ * You should prefer using this over {@link method} when proxying, since this does not block IO.
+ * Note that this is functionally the same as {@link method} on exported objects.
+ * ```
+ */
+export declare function methodAsync<const InArgs extends Array<DBusType>>(...inArgs: InArgs): (method: (this: Service, ...args: InferVariantTypes<InArgs>) => Promise<void>, ctx: ClassMethodDecoratorContext<Service, typeof method>) => void;
+/**
+ * Registers a read-write property. When a new value is assigned the notify signal
+ * is automatically emitted on the local and exported object.
+ *
+ * Note that new values are checked by reference so assigning the same object will
+ * not emit the notify signal.
+ * ```
+ */
+export declare function property<T extends string>(type: T): (_: void, ctx: ClassFieldDecoratorContext<Service, InferVariantType<T>>) => (this: Service, init: InferVariantType<T>) => InferVariantType<T>;
+/**
+ * Registers a read-only property. Can be used in conjuction with {@link setter} to define
+ * read-write properties as accessors.
+ *
+ * Note that you will need to explicitly emit the notify signal.
+ */
+export declare function getter<T extends string>(type: T): (getter: (this: Service) => InferVariantType<T>, ctx: ClassGetterDecoratorContext<Service, InferVariantType<T>>) => (this: Service) => InferVariantType<T>;
+/**
+ * Registers a write-only property. Can be used in conjuction with {@link getter} to define
+ * read-write properties as accessors.
+ *
+ * Note that you will need to explicitly emit the notify signal.
+ */
+export declare function setter<T extends string>(type: T): (setter: (this: Service, value: InferVariantType<T>) => void, ctx: ClassSetterDecoratorContext<Service, InferVariantType<T>>) => (this: Service, value: InferVariantType<T>) => void;
+/**
+ * Registers a signal which when invoked will emit the signal
+ * on the local object and the exported object.
+ *
+ * Note that its not possible to emit signals on remote objects through proxies.
+ */
+export declare function signal<const Params extends Array<DBusType>>(...params: Params): (method: (this: Service, ...params: InferVariantTypes<Params>) => void, ctx: ClassMethodDecoratorContext<Service, typeof method>) => typeof method;
+declare class GLibVariant<T extends string = any> extends GLib.Variant<T> {
+    static new<T extends string>(signature: T, value: InferVariantType<T>): GLib.Variant<T>;
+    constructor(signature: T, value: InferVariantType<T>);
+    deepUnpack<V = InferVariantType<T>>(): V;
+    deep_unpack<V = InferVariantType<T>>(): V;
+}
+export declare const Variant: typeof GLibVariant;
+export type Variant<T extends string = any> = GLibVariant<T>;
+export {};