@devscholar/node-with-gjs 0.0.0 → 0.0.2

package/README.md

@@ -31,87 +31,17 @@ pacman -S gtk4 webkitgtk-6.0 gjs
 
 # Usage
 
-## Runtime Support
+For more examples and details, see the [node-with-gjs-examples README](https://github.com/devscholar/node-with-gjs-examples).
 
-| Runtime | `gi://` URL Syntax | Loader Hooks |
-|---------|-------------------|--------------|
-| Node.js | ✅ Supported | ✅ `--experimental-loader` |
-| Bun | ❌ Not supported | ❌ No hooks mechanism |
-| Deno | ❌ Not supported | ❌ No hooks mechanism |
+# Tests
 
-## Node.js
-
-Node.js supports the `gi://` URL syntax, which is consistent with GJS:
-
-```typescript
-import Gtk from 'gi://Gtk?version=4.0';
-import WebKit from 'gi://WebKit?version=6.0';
-
-const app = new Gtk.Application({ application_id: 'org.example.app' });
-// ...
-```
-
-## Bun / Deno
-
-Bun and Deno do not support Node.js loader hooks, so you need to use the `loadGi` function instead:
-
-```typescript
-import { loadGi } from './gi-loader.ts';
-
-const Gtk = loadGi('Gtk', '4.0');
-const WebKit = loadGi('WebKit', '6.0');
-
-const app = new Gtk.Application({ application_id: 'org.example.app' });
-// ...
-```
-
-**Note:** The `loadGi` function also works with Node.js, useful for older Node.js versions or when not using experimental loader flags.
-
-# Examples
-
-## Console Apps
-
-### Console Input App
-
-```bash
-node start.js examples/console/console-input/console-input.ts
-```
-
-### Await Delay App
+Run all tests:
 
 ```bash
-node start.js examples/console/await-delay/await-delay.ts
+npm test
 ```
 
-## GUI Apps
-
-### GTK4 Counter App
-
-```bash
-node start.js examples/gtk/counter/counter.ts
-```
-
-### GTK4 Drag Box App
-
-A drag box example that demonstrates high frequency IPC.
-
-```bash
-node start.js examples/gtk/drag-box/drag-box.ts
-```
-
-### GTK4 WebKit Counter App
-
-```bash
-node start.js examples/gtk-webkit/counter/counter.ts
-```
-
-### Adwaita Counter App (libadwaita)
-
-A counter example based on [libadwaita](https://gnome.pages.gitlab.gnome.org/libadwaita/), demonstrating how to use Adwaita-specific components like `Adw.ApplicationWindow` and `Adw.Clamp`.
-
-```bash
-node start.js examples/adwaita/counter/counter.ts
-```
+For detailed testing documentation, see [docs/testing.md](docs/testing.md).
 
 # License
 

package/__tests__/basic.test.ts

@@ -0,0 +1,41 @@
+import { jest } from '@jest/globals';
+
+const isLinux = process.platform === 'linux' || process.platform === 'darwin';
+
+(isLinux ? describe : describe.skip)('Basic Module Tests', () => {
+  let gjs: any;
+
+  beforeAll(async () => {
+    try {
+      gjs = await import('../src/index.js');
+      gjs.init();
+    } catch (e) {
+      console.log('Skipping basic tests - load failed:', e);
+    }
+  });
+
+  afterAll(() => {
+  });
+
+  it('should export init function', () => {
+    expect(gjs.init).toBeDefined();
+    expect(typeof gjs.init).toBe('function');
+  });
+
+  it('should export imports object', () => {
+    expect(gjs.imports).toBeDefined();
+    expect(gjs.imports.gi).toBeDefined();
+  });
+
+  it('should have gi proxy', () => {
+    const gi = gjs.imports.gi;
+    expect(gi).toBeDefined();
+    expect(typeof gi).toBe('object');
+  });
+
+  it('should support gi.versions', () => {
+    const gi = gjs.imports.gi;
+    expect(gi.versions).toBeDefined();
+    expect(typeof gi.versions).toBe('object');
+  });
+});

package/__tests__/glib.test.ts

@@ -0,0 +1,72 @@
+import { jest } from '@jest/globals';
+
+const isLinux = process.platform === 'linux' || process.platform === 'darwin';
+
+(isLinux ? describe : describe.skip)('GLib Tests', () => {
+  let gjs: any;
+  let GLib: any;
+
+  beforeAll(async () => {
+    try {
+      gjs = await import('../src/index.js');
+      gjs.init();
+      const gi = gjs.imports.gi;
+      GLib = gi.GLib;
+    } catch (e) {
+      console.log('Skipping GLib tests - load failed:', e);
+    }
+  }, 60000);
+
+  afterAll(() => {
+  });
+
+  it('should load GLib namespace', () => {
+    expect(GLib).toBeDefined();
+  });
+
+  it('should get user name', () => {
+    const userName = GLib.get_user_name();
+    expect(userName).toBeDefined();
+    expect(typeof userName).toBe('string');
+  });
+
+  it('should get home dir', () => {
+    const home = GLib.get_home_dir();
+    expect(home).toBeDefined();
+    expect(typeof home).toBe('string');
+  });
+
+  it('should get tmp dir', () => {
+    const tmp = GLib.get_tmp_dir();
+    expect(tmp).toBeDefined();
+    expect(typeof tmp).toBe('string');
+  });
+});
+
+(isLinux ? describe : describe.skip)('GObject Tests', () => {
+  let gjs: any;
+  let GObject: any;
+
+  beforeAll(async () => {
+    try {
+      gjs = await import('../src/index.js');
+      gjs.init();
+      const gi = gjs.imports.gi;
+      GObject = gi.GObject;
+    } catch (e) {
+      console.log('Skipping GObject tests - load failed:', e);
+    }
+  }, 60000);
+
+  afterAll(() => {
+  });
+
+  it('should load GObject namespace', () => {
+    expect(GObject).toBeDefined();
+  });
+
+  it('should have type system', () => {
+    expect(GObject.type_from_name).toBeDefined();
+    expect(GObject.type_register_fundamental).toBeDefined();
+  });
+});

package/__tests__/gtk4.test.ts

@@ -0,0 +1,73 @@
+import { jest } from '@jest/globals';
+
+const isLinux = process.platform === 'linux' || process.platform === 'darwin';
+
+(isLinux ? describe : describe.skip)('GTK4 GUI Tests', () => {
+  let gjs: any;
+  let Gtk: any;
+  let GLib: any;
+
+  beforeAll(async () => {
+    try {
+      gjs = await import('../src/index.js');
+      gjs.init();
+      const gi = gjs.imports.gi;
+      gi.versions.Gtk = '4.0';
+      Gtk = gi.Gtk;
+      GLib = gi.GLib;
+      Gtk.init();
+    } catch (e) {
+      console.log('Skipping GTK4 tests - load failed:', e);
+    }
+  }, 60000);
+
+  afterAll(() => {
+  });
+
+  it('should load Gtk namespace', () => {
+    expect(Gtk).toBeDefined();
+    expect(Gtk.Application).toBeDefined();
+  });
+
+  it('should load GLib namespace', () => {
+    expect(GLib).toBeDefined();
+  });
+
+  it('should create an Application instance', () => {
+    const app = new Gtk.Application({ application_id: 'org.test.app' });
+    expect(app).toBeDefined();
+  });
+
+  it('should create a Box container', () => {
+    const box = new Gtk.Box({ orientation: Gtk.Orientation.VERTICAL, spacing: 10 });
+    expect(box).toBeDefined();
+  });
+
+  it('should create a Label', () => {
+    const label = new Gtk.Label({ label: 'Test Label' });
+    expect(label).toBeDefined();
+    expect(label.get_label()).toBe('Test Label');
+  });
+
+  it('should create a Button', () => {
+    const button = new Gtk.Button({ label: 'Click Me' });
+    expect(button).toBeDefined();
+  });
+
+  it('should set Label text', () => {
+    const label = new Gtk.Label({ label: 'Initial' });
+    label.set_label('Updated');
+    expect(label.get_label()).toBe('Updated');
+  });
+
+  it('should use Orientation enum', () => {
+    expect(Gtk.Orientation.VERTICAL).toBeDefined();
+    expect(Gtk.Orientation.HORIZONTAL).toBeDefined();
+  });
+
+  it('should use Align enum', () => {
+    expect(Gtk.Align.CENTER).toBeDefined();
+    expect(Gtk.Align.START).toBeDefined();
+    expect(Gtk.Align.END).toBeDefined();
+  });
+});

package/dist/index.js

@@ -0,0 +1,211 @@
+// src/index.ts
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as cp from 'node:child_process';
+import * as os from 'node:os';
+import { fileURLToPath } from 'node:url';
+import { IpcSync } from './ipc.js';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const gcRegistry = new FinalizationRegistry((id) => {
+    try {
+        if (ipc)
+            ipc.send({ action: 'Release', targetId: id });
+    }
+    catch { }
+});
+const callbackRegistry = new Map();
+let ipc = null;
+let proc = null;
+let initialized = false;
+let reqPath = '';
+let resPath = '';
+function cleanup() {
+    if (!initialized)
+        return;
+    initialized = false;
+    if (ipc)
+        try {
+            ipc.close();
+        }
+        catch { }
+    if (proc && !proc.killed)
+        try {
+            proc.kill('SIGKILL');
+        }
+        catch { }
+    if (fs.existsSync(reqPath))
+        try {
+            fs.unlinkSync(reqPath);
+        }
+        catch { }
+    if (fs.existsSync(resPath))
+        try {
+            fs.unlinkSync(resPath);
+        }
+        catch { }
+    proc = null;
+    ipc = null;
+}
+function findGjsPath() {
+    try {
+        const result = cp.execSync('which gjs', { encoding: 'utf-8' }).trim();
+        return result || 'gjs';
+    }
+    catch {
+        return 'gjs';
+    }
+}
+function initialize() {
+    if (initialized)
+        return;
+    const token = `${process.pid}-${Date.now()}`;
+    reqPath = path.join(os.tmpdir(), `gjs-req-${token}.pipe`);
+    resPath = path.join(os.tmpdir(), `gjs-res-${token}.pipe`);
+    try {
+        cp.execSync(`mkfifo "${reqPath}"`);
+        cp.execSync(`mkfifo "${resPath}"`);
+    }
+    catch (e) {
+        console.error("Failed to create Unix FIFOs");
+        process.exit(1);
+    }
+    const scriptPath = path.join(__dirname, '..', 'scripts', 'host.js');
+    const gjsPath = findGjsPath();
+    proc = cp.spawn('bash', ['-c', `exec "${gjsPath}" -m "${scriptPath}" 3<"${reqPath}" 4>"${resPath}"`], {
+        stdio: 'inherit',
+        env: process.env
+    });
+    proc.unref();
+    process.on('beforeExit', () => { cleanup(); process.exit(0); });
+    process.on('exit', cleanup);
+    process.on('SIGINT', () => { cleanup(); process.exit(0); });
+    process.on('uncaughtException', (err) => {
+        console.error('Node.js Exception:', err);
+        cleanup();
+        process.exit(1);
+    });
+    const fdWrite = fs.openSync(reqPath, 'w');
+    const fdRead = fs.openSync(resPath, 'r');
+    ipc = new IpcSync(fdRead, fdWrite, (res) => {
+        const cb = callbackRegistry.get(res.callbackId);
+        if (cb) {
+            const wrappedArgs = (res.args || []).map((arg) => createProxy(arg));
+            return cb(...wrappedArgs);
+        }
+        return null;
+    });
+    globalThis.print = (...args) => {
+        ipc.send({ action: 'Print', args: args.map(wrapArg) });
+    };
+    initialized = true;
+}
+function wrapArg(arg) {
+    if (arg === null || arg === undefined)
+        return { type: 'null' };
+    if (arg.__ref)
+        return { type: 'ref', id: arg.__ref };
+    if (arg instanceof Uint8Array) {
+        return { type: 'uint8array', value: Array.from(arg) };
+    }
+    if (typeof arg === 'function') {
+        const cbId = `cb_${Date.now()}_${Math.random()}`;
+        callbackRegistry.set(cbId, arg);
+        return { type: 'callback', callbackId: cbId };
+    }
+    if (Array.isArray(arg))
+        return { type: 'array', value: arg.map(wrapArg) };
+    if (typeof arg === 'object') {
+        const plainObj = {};
+        for (let k in arg)
+            plainObj[k] = wrapArg(arg[k]);
+        return { type: 'object', value: plainObj };
+    }
+    return { type: 'primitive', value: arg };
+}
+function createProxy(meta) {
+    if (meta.type === 'primitive' || meta.type === 'null')
+        return meta.value;
+    if (meta.type === 'array')
+        return meta.value.map((item) => createProxy(item));
+    if (meta.type !== 'ref')
+        return undefined;
+    const id = meta.id;
+    const stub = function () { };
+    const proxy = new Proxy(stub, {
+        get: (target, prop) => {
+            if (prop === '__ref')
+                return id;
+            if (typeof prop !== 'string')
+                return undefined;
+            const val = ipc.send({ action: 'Get', targetId: id, property: prop });
+            if (val && val.type === 'function') {
+                return new Proxy(function () { }, {
+                    apply: (t, thisArg, args) => {
+                        const netArgs = args.map(wrapArg);
+                        const res = ipc.send({ action: 'Invoke', targetId: id, methodName: prop, args: netArgs });
+                        return createProxy(res);
+                    },
+                    construct: (t, args) => {
+                        const netArgs = args.map(wrapArg);
+                        const res = ipc.send({ action: 'NewProp', targetId: id, property: prop, args: netArgs });
+                        return createProxy(res);
+                    }
+                });
+            }
+            return createProxy(val);
+        },
+        set: (target, prop, value) => {
+            if (typeof prop !== 'string')
+                return false;
+            ipc.send({ action: 'Set', targetId: id, property: prop, value: wrapArg(value) });
+            return true;
+        },
+        construct: (target, args) => {
+            const netArgs = args.map(wrapArg);
+            const res = ipc.send({ action: 'New', typeId: id, args: netArgs });
+            return createProxy(res);
+        }
+    });
+    gcRegistry.register(proxy, id);
+    return proxy;
+}
+export function init() {
+    initialize();
+}
+// Internal function - not exposed to users
+function loadGiNamespace(namespace, version) {
+    initialize();
+    const res = ipc.send({ action: 'LoadNamespace', namespace, version });
+    return createProxy(res);
+}
+// Namespace cache to avoid creating multiple proxies for the same namespace
+const namespaceCache = new Map();
+// GI namespace versions
+const giVersions = {};
+// Create the gi proxy with lazy loading and caching
+const giProxy = new Proxy({}, {
+    get(_, namespace) {
+        if (namespace === 'versions') {
+            return new Proxy(giVersions, {
+                set(target, prop, value) {
+                    target[prop] = value;
+                    // Clear cache for this namespace when version changes
+                    const cacheKey = `${prop}@default`;
+                    namespaceCache.delete(cacheKey);
+                    return true;
+                }
+            });
+        }
+        const version = giVersions[namespace];
+        const cacheKey = `${namespace}@${version || 'default'}`;
+        if (!namespaceCache.has(cacheKey)) {
+            namespaceCache.set(cacheKey, loadGiNamespace(namespace, version));
+        }
+        return namespaceCache.get(cacheKey);
+    }
+});
+// The main exports object - compatible with GJS imports
+export const imports = {
+    gi: giProxy
+};

package/dist/ipc.js

@@ -0,0 +1,103 @@
+// src/ipc.ts
+import * as fs from 'node:fs';
+// Use a global/shared read buffer to handle redundant data across calls
+let readBuffer = Buffer.alloc(0);
+export function readLineSync(fd) {
+    while (true) {
+        // 1. If the buffer already contains a complete line, extract and return it with minimal overhead
+        const newlineIdx = readBuffer.indexOf(10); // 10 is the ASCII code for \n
+        if (newlineIdx !== -1) {
+            const line = readBuffer.subarray(0, newlineIdx).toString('utf8');
+            readBuffer = readBuffer.subarray(newlineIdx + 1);
+            return line;
+        }
+        // 2. Otherwise, try to read a large chunk from the pipe
+        const chunk = Buffer.alloc(8192); // Attempt to read 8KB each time
+        let bytesRead = 0;
+        try {
+            bytesRead = fs.readSync(fd, chunk, 0, 8192, null);
+        }
+        catch (e) {
+            return null;
+        }
+        if (bytesRead === 0) {
+            if (readBuffer.length === 0)
+                return null;
+            const line = readBuffer.toString('utf8');
+            readBuffer = Buffer.alloc(0);
+            return line;
+        }
+        // 3. Append the newly read data to the buffer
+        readBuffer = Buffer.concat([readBuffer, chunk.subarray(0, bytesRead)]);
+    }
+}
+export class IpcSync {
+    fdRead;
+    fdWrite;
+    onEvent;
+    exited = false;
+    constructor(fdRead, fdWrite, onEvent) {
+        this.fdRead = fdRead;
+        this.fdWrite = fdWrite;
+        this.onEvent = onEvent;
+    }
+    send(cmd) {
+        if (this.exited)
+            return { type: 'exit' };
+        try {
+            fs.writeSync(this.fdWrite, JSON.stringify(cmd) + '\n');
+        }
+        catch (e) {
+            throw new Error("Pipe closed (Write failed)");
+        }
+        while (true) {
+            const line = readLineSync(this.fdRead);
+            if (line === null)
+                throw new Error("Pipe closed (Read EOF)");
+            if (!line.trim())
+                continue;
+            let res;
+            try {
+                res = JSON.parse(line);
+            }
+            catch (e) {
+                throw new Error(`Invalid JSON from host: ${line}`);
+            }
+            if (res.type === 'event') {
+                let result = null;
+                try {
+                    result = this.onEvent(res);
+                }
+                catch (e) {
+                    console.error("Callback Error:", e);
+                }
+                const reply = { type: 'reply', result: result };
+                try {
+                    fs.writeSync(this.fdWrite, JSON.stringify(reply) + '\n');
+                }
+                catch { }
+                continue;
+            }
+            if (res.type === 'error')
+                throw new Error(`GJS Host Error: ${res.message}`);
+            if (res.type === 'exit') {
+                this.exited = true;
+                return res;
+            }
+            return res;
+        }
+    }
+    close() {
+        this.exited = true;
+        if (this.fdRead)
+            try {
+                fs.closeSync(this.fdRead);
+            }
+            catch { }
+        if (this.fdWrite)
+            try {
+                fs.closeSync(this.fdWrite);
+            }
+            catch { }
+    }
+}

package/docs/testing.md

@@ -0,0 +1,100 @@
+# Testing Guide
+
+This document describes how to run tests for the `node-with-gjs` project.
+
+## Running Tests
+
+### Run All Tests
+
+```bash
+npm test
+```
+
+### Run Specific Test Files
+
+```bash
+npm test -- --testPathPatterns=gtk4
+npm test -- --testPathPatterns=glib
+npm test -- --testPathPatterns=basic
+```
+
+## Test Configuration
+
+Tests are configured to run **serially** (`maxWorkers: 1`) because the module uses a singleton pattern with global state for the IPC connection to GJS. Running tests in parallel would cause conflicts between multiple GJS processes.
+
+If you need to run tests in parallel, you would need to refactor the module to support multiple instances (see [jest.config.js](../jest.config.js)).
+
+## Test Files
+
+Test files are located in the `__tests__` directory:
+
+| File | Description |
+|------|-------------|
+| `basic.test.ts` | Basic module functionality tests (init, imports.gi) |
+| `gtk4.test.ts` | GTK4 GUI component tests (Application, Box, Label, Button, enums) |
+| `glib.test.ts` | GLib and GObject tests (get_user_name, get_home_dir, etc.) |
+
+## Platform Support
+
+| Platform | Support |
+|----------|---------|
+| Linux | All tests run normally |
+| macOS | Tests are skipped (GJS is Linux-only) |
+| Windows | Tests are skipped (GJS is Linux-only) |
+
+Tests automatically detect the platform and skip on non-Linux systems.
+
+## GUI Testing
+
+GUI tests create GTK objects in memory without displaying windows. This allows testing without interfering with the desktop environment. The tests verify:
+
+- Object creation (Application, Window, Box, Label, Button)
+- Property getters/setters
+- Method calls
+- Enum values
+
+For testing with actual window display and event handling, see the [node-with-gjs-examples](https://github.com/devscholar/node-with-gjs-examples) repository.
+
+## Writing New Tests
+
+When writing new tests, keep in mind:
+
+1. **Initialize the module**: Always call `gjs.init()` in `beforeAll`
+2. **Set GTK version**: Use `gi.versions.Gtk = '4.0'` before accessing Gtk
+3. **Initialize GTK**: Call `Gtk.init()` before creating GTK objects
+4. **Platform check**: Tests automatically skip on non-Linux platforms via `const isLinux = process.platform === 'linux' || process.platform === 'darwin'`
+
+Example test structure:
+
+```typescript
+import { jest } from '@jest/globals';
+
+const isLinux = process.platform === 'linux' || process.platform === 'darwin';
+
+(isLinux ? describe : describe.skip)('My Tests', () => {
+  let gjs: any;
+  let Gtk: any;
+
+  beforeAll(async () => {
+    try {
+      gjs = await import('../src/index.js');
+      gjs.init();
+      const gi = gjs.imports.gi;
+      gi.versions.Gtk = '4.0';
+      Gtk = gi.Gtk;
+      Gtk.init();
+    } catch (e) {
+      console.log('Skipping tests - load failed:', e);
+    }
+  }, 60000);
+
+  afterAll(() => {
+    // Cleanup if needed
+  });
+
+  it('should create a widget', () => {
+    const widget = new Gtk.Label({ label: 'Test' });
+    expect(widget).toBeDefined();
+  });
+});
+```