@gjsify/dgram 0.1.0

package/README.md

@@ -0,0 +1,29 @@
+# @gjsify/dgram
+
+GJS implementation of the Node.js `dgram` module using Gio.Socket for UDP networking.
+
+Part of the [gjsify](https://github.com/gjsify/gjsify) project — Node.js and Web APIs for GJS (GNOME JavaScript).
+
+## Installation
+
+```bash
+npm install @gjsify/dgram
+# or
+yarn add @gjsify/dgram
+```
+
+## Usage
+
+```typescript
+import { createSocket } from '@gjsify/dgram';
+
+const socket = createSocket('udp4');
+socket.bind(41234);
+socket.on('message', (msg, rinfo) => {
+  console.log(`Received: ${msg} from ${rinfo.address}:${rinfo.port}`);
+});
+```
+
+## License
+
+MIT

package/lib/esm/index.js

@@ -0,0 +1,370 @@
+import Gio from "@girs/gio-2.0";
+import GLib from "@girs/glib-2.0";
+import { EventEmitter } from "node:events";
+import { Buffer } from "node:buffer";
+import { deferEmit, ensureMainLoop } from "@gjsify/utils";
+const _activeSockets = /* @__PURE__ */ new Set();
+class Socket extends EventEmitter {
+  type;
+  _socket = null;
+  _bound = false;
+  _closed = false;
+  _receiving = false;
+  _address = { address: "0.0.0.0", family: "IPv4", port: 0 };
+  _cancellable = new Gio.Cancellable();
+  _reuseAddr;
+  _connected = false;
+  _remoteAddress = null;
+  constructor(options) {
+    super();
+    if (typeof options === "string") {
+      this.type = options;
+      this._reuseAddr = false;
+    } else {
+      this.type = options.type;
+      this._reuseAddr = options.reuseAddr ?? false;
+    }
+    const family = this.type === "udp6" ? Gio.SocketFamily.IPV6 : Gio.SocketFamily.IPV4;
+    try {
+      this._socket = Gio.Socket.new(family, Gio.SocketType.DATAGRAM, Gio.SocketProtocol.UDP);
+      this._socket.set_blocking(false);
+    } catch (err) {
+      this._socket = null;
+      deferEmit(this, "error", err);
+    }
+  }
+  /**
+   * Bind the socket to a port and optional address.
+   */
+  bind(port, address, callback) {
+    if (this._closed || !this._socket) return this;
+    let bindPort = 0;
+    let bindAddress = this.type === "udp6" ? "::" : "0.0.0.0";
+    if (typeof port === "object") {
+      const opts = port;
+      bindPort = opts.port || 0;
+      bindAddress = opts.address || bindAddress;
+      if (typeof address === "function") callback = address;
+    } else if (typeof port === "number") {
+      bindPort = port;
+      if (typeof address === "string") bindAddress = address;
+      else if (typeof address === "function") callback = address;
+    } else if (typeof port === "function") {
+      callback = port;
+    }
+    if (callback) this.once("listening", callback);
+    try {
+      const family = this.type === "udp6" ? Gio.SocketFamily.IPV6 : Gio.SocketFamily.IPV4;
+      const inetAddr = Gio.InetAddress.new_from_string(bindAddress) || (family === Gio.SocketFamily.IPV6 ? Gio.InetAddress.new_any(Gio.SocketFamily.IPV6) : Gio.InetAddress.new_any(Gio.SocketFamily.IPV4));
+      const sockAddr = new Gio.InetSocketAddress({ address: inetAddr, port: bindPort });
+      this._socket.bind(sockAddr, this._reuseAddr);
+      this._bound = true;
+      _activeSockets.add(this);
+      ensureMainLoop();
+      const localAddr = this._socket.get_local_address();
+      if (localAddr) {
+        this._address = {
+          address: localAddr.get_address().to_string(),
+          family: this.type === "udp6" ? "IPv6" : "IPv4",
+          port: localAddr.get_port()
+        };
+      }
+      setTimeout(() => {
+        this.emit("listening");
+        this._startReceiving();
+      }, 0);
+    } catch (err) {
+      deferEmit(this, "error", err);
+    }
+    return this;
+  }
+  /**
+   * Send a message.
+   */
+  send(msg, offset, length, port, address, callback) {
+    if (this._closed || !this._socket) return;
+    let buf;
+    let destPort;
+    let destAddress;
+    let cb;
+    if (typeof offset === "function") {
+      cb = offset;
+      buf = this._toBuffer(msg);
+      destPort = this._address.port;
+      destAddress = this._address.address;
+    } else if (typeof offset === "number" && typeof length === "string") {
+      destPort = offset;
+      destAddress = length;
+      cb = port;
+      buf = this._toBuffer(msg);
+    } else if (typeof offset === "number" && typeof length === "number" && typeof address === "function") {
+      cb = address;
+      destPort = port;
+      destAddress = this.type === "udp6" ? "::1" : "127.0.0.1";
+      buf = this._toBufferSlice(msg, offset, length);
+    } else if (typeof offset === "number" && typeof length === "number") {
+      destPort = port;
+      destAddress = address || (this.type === "udp6" ? "::1" : "127.0.0.1");
+      cb = callback;
+      buf = this._toBufferSlice(msg, offset, length);
+    } else {
+      destPort = Number(offset) || 0;
+      destAddress = this.type === "udp6" ? "::1" : "127.0.0.1";
+      buf = this._toBuffer(msg);
+    }
+    try {
+      const inetAddr = Gio.InetAddress.new_from_string(destAddress);
+      const sockAddr = new Gio.InetSocketAddress({ address: inetAddr, port: destPort });
+      if (!this._bound) {
+        const anyAddr = this.type === "udp6" ? Gio.InetAddress.new_any(Gio.SocketFamily.IPV6) : Gio.InetAddress.new_any(Gio.SocketFamily.IPV4);
+        const anySockAddr = new Gio.InetSocketAddress({ address: anyAddr, port: 0 });
+        this._socket.bind(anySockAddr, false);
+        this._bound = true;
+      }
+      const bytesSent = this._socket.send_to(sockAddr, buf, this._cancellable);
+      if (cb) cb(null, bytesSent);
+    } catch (err) {
+      if (cb) cb(err instanceof Error ? err : new Error(String(err)), 0);
+      else this.emit("error", err);
+    }
+  }
+  _toBuffer(msg) {
+    if (Array.isArray(msg)) {
+      return Buffer.concat(msg.map((m) => typeof m === "string" ? Buffer.from(m) : Buffer.from(m)));
+    }
+    return typeof msg === "string" ? Buffer.from(msg) : Buffer.from(msg);
+  }
+  _toBufferSlice(msg, offset, length) {
+    const buf = this._toBuffer(msg);
+    return Buffer.from(buf.buffer, buf.byteOffset + offset, length);
+  }
+  /**
+   * Close the socket.
+   */
+  close(callback) {
+    if (this._closed) {
+      throw new Error("Not running");
+    }
+    this._closed = true;
+    _activeSockets.delete(this);
+    if (callback) this.once("close", callback);
+    this._cancellable.cancel();
+    if (this._socket) {
+      try {
+        this._socket.close();
+      } catch (_e) {
+      }
+      this._socket = null;
+    }
+    deferEmit(this, "close");
+    return this;
+  }
+  /**
+   * Associate the socket with a remote address/port (connected UDP).
+   * After connect(), send() can omit address and port.
+   */
+  connect(port, address, callback) {
+    if (this._connected) {
+      const err = new Error("Already connected");
+      err.code = "ERR_SOCKET_DGRAM_IS_CONNECTED";
+      throw err;
+    }
+    if (!port || port <= 0 || port >= 65536) {
+      const err = new RangeError(`Port should be > 0 and < 65536. Received ${port}.`);
+      err.code = "ERR_SOCKET_BAD_PORT";
+      throw err;
+    }
+    let resolvedAddr;
+    let cb;
+    if (typeof address === "function") {
+      cb = address;
+      resolvedAddr = this.type === "udp6" ? "::1" : "127.0.0.1";
+    } else {
+      resolvedAddr = address || (this.type === "udp6" ? "::1" : "127.0.0.1");
+      cb = callback;
+    }
+    this._connected = true;
+    this._remoteAddress = {
+      address: resolvedAddr,
+      family: this.type === "udp6" ? "IPv6" : "IPv4",
+      port
+    };
+    if (cb) {
+      Promise.resolve().then(() => {
+        this.emit("connect");
+        cb();
+      });
+    } else {
+      Promise.resolve().then(() => this.emit("connect"));
+    }
+  }
+  /**
+   * Dissociate a connected socket from its remote address.
+   */
+  disconnect() {
+    if (!this._connected) {
+      const err = new Error("Not connected");
+      err.code = "ERR_SOCKET_DGRAM_NOT_CONNECTED";
+      throw err;
+    }
+    this._connected = false;
+    this._remoteAddress = null;
+  }
+  /**
+   * Returns the remote address of a connected socket.
+   * Throws ERR_SOCKET_DGRAM_NOT_CONNECTED if not connected.
+   */
+  remoteAddress() {
+    if (!this._connected || !this._remoteAddress) {
+      const err = new Error("Not connected");
+      err.code = "ERR_SOCKET_DGRAM_NOT_CONNECTED";
+      throw err;
+    }
+    return { ...this._remoteAddress };
+  }
+  /**
+   * Get the bound address info.
+   */
+  address() {
+    return { ...this._address };
+  }
+  /**
+   * Set the broadcast flag.
+   */
+  setBroadcast(flag) {
+    if (this._socket) {
+      this._socket.set_broadcast(flag);
+    }
+  }
+  /**
+   * Set the TTL.
+   */
+  setTTL(ttl) {
+    if (this._socket) {
+      this._socket.set_ttl(ttl);
+    }
+    return ttl;
+  }
+  /**
+   * Set multicast TTL.
+   */
+  setMulticastTTL(ttl) {
+    if (this._socket) {
+      this._socket.set_multicast_ttl(ttl);
+    }
+    return ttl;
+  }
+  /**
+   * Set multicast loopback.
+   */
+  setMulticastLoopback(flag) {
+    if (this._socket) {
+      this._socket.set_multicast_loopback(flag);
+    }
+    return flag;
+  }
+  /**
+   * Add multicast group membership.
+   */
+  addMembership(multicastAddress, multicastInterface) {
+    if (!this._socket) return;
+    try {
+      const mcastAddr = Gio.InetAddress.new_from_string(multicastAddress);
+      this._socket.join_multicast_group(mcastAddr, false, multicastInterface || null);
+    } catch (err) {
+      this.emit("error", err);
+    }
+  }
+  /**
+   * Drop multicast group membership.
+   */
+  dropMembership(multicastAddress, multicastInterface) {
+    if (!this._socket) return;
+    try {
+      const mcastAddr = Gio.InetAddress.new_from_string(multicastAddress);
+      this._socket.leave_multicast_group(mcastAddr, false, multicastInterface || null);
+    } catch (err) {
+      this.emit("error", err);
+    }
+  }
+  /**
+   * Set multicast interface.
+   */
+  setMulticastInterface(_interfaceAddress) {
+  }
+  /** Ref the socket (keep event loop alive). */
+  ref() {
+    return this;
+  }
+  /** Unref the socket (allow event loop to exit). */
+  unref() {
+    return this;
+  }
+  /** Get/Set receive buffer size. */
+  getRecvBufferSize() {
+    return 65536;
+  }
+  setRecvBufferSize(_size) {
+  }
+  /** Get/Set send buffer size. */
+  getSendBufferSize() {
+    return 65536;
+  }
+  setSendBufferSize(_size) {
+  }
+  /**
+   * Start receiving messages in background.
+   */
+  _startReceiving() {
+    if (this._receiving || this._closed || !this._socket) return;
+    this._receiving = true;
+    this._receiveLoop();
+  }
+  _receiveLoop() {
+    if (this._closed || !this._socket) return;
+    try {
+      if (!this._socket.condition_check(GLib.IOCondition.IN)) {
+        setTimeout(() => this._receiveLoop(), 50);
+        return;
+      }
+      const buf = new Uint8Array(65536);
+      const result = this._socket.receive_from(buf, this._cancellable);
+      const bytesRead = Array.isArray(result) ? result[0] : result;
+      const srcAddr = Array.isArray(result) ? result[1] : null;
+      if (bytesRead > 0 && srcAddr) {
+        const data = Buffer.from(buf.subarray(0, bytesRead));
+        const inetSockAddr = srcAddr;
+        const rinfo = {
+          address: inetSockAddr.get_address().to_string(),
+          family: this.type === "udp6" ? "IPv6" : "IPv4",
+          port: inetSockAddr.get_port()
+        };
+        this.emit("message", data, rinfo);
+      }
+      if (!this._closed) {
+        setTimeout(() => this._receiveLoop(), 0);
+      }
+    } catch (err) {
+      if (!this._closed) {
+        const errObj = err;
+        if (errObj.code !== Gio.IOErrorEnum.CANCELLED) {
+          this.emit("error", err);
+        }
+      }
+    }
+  }
+}
+function createSocket(type, callback) {
+  const opts = typeof type === "string" ? { type } : type;
+  const socket = new Socket(opts);
+  if (callback) {
+    socket.on("message", callback);
+  }
+  return socket;
+}
+var index_default = { Socket, createSocket };
+export {
+  Socket,
+  createSocket,
+  index_default as default
+};

package/lib/types/index.d.ts

@@ -0,0 +1,125 @@
+import { EventEmitter } from 'node:events';
+import { Buffer } from 'node:buffer';
+export interface SocketOptions {
+    type: 'udp4' | 'udp6';
+    reuseAddr?: boolean;
+    reusePort?: boolean;
+    ipv6Only?: boolean;
+    recvBufferSize?: number;
+    sendBufferSize?: number;
+    signal?: AbortSignal;
+}
+export interface AddressInfo {
+    address: string;
+    family: string;
+    port: number;
+}
+/**
+ * dgram.Socket — UDP socket wrapping Gio.Socket.
+ */
+interface RemoteAddressInfo {
+    address: string;
+    family: string;
+    port: number;
+}
+export declare class Socket extends EventEmitter {
+    readonly type: 'udp4' | 'udp6';
+    private _socket;
+    private _bound;
+    private _closed;
+    private _receiving;
+    private _address;
+    private _cancellable;
+    private _reuseAddr;
+    private _connected;
+    private _remoteAddress;
+    constructor(options: SocketOptions | string);
+    /**
+     * Bind the socket to a port and optional address.
+     */
+    bind(port?: number | {
+        port?: number;
+        address?: string;
+        exclusive?: boolean;
+    }, address?: string | (() => void), callback?: () => void): this;
+    /**
+     * Send a message.
+     */
+    send(msg: Buffer | string | Uint8Array | (Buffer | string | Uint8Array)[], offset?: number | ((err: Error | null, bytes: number) => void), length?: number, port?: number, address?: string | ((err: Error | null, bytes: number) => void), callback?: (err: Error | null, bytes: number) => void): void;
+    private _toBuffer;
+    private _toBufferSlice;
+    /**
+     * Close the socket.
+     */
+    close(callback?: () => void): this;
+    /**
+     * Associate the socket with a remote address/port (connected UDP).
+     * After connect(), send() can omit address and port.
+     */
+    connect(port: number, address?: string | (() => void), callback?: () => void): void;
+    /**
+     * Dissociate a connected socket from its remote address.
+     */
+    disconnect(): void;
+    /**
+     * Returns the remote address of a connected socket.
+     * Throws ERR_SOCKET_DGRAM_NOT_CONNECTED if not connected.
+     */
+    remoteAddress(): RemoteAddressInfo;
+    /**
+     * Get the bound address info.
+     */
+    address(): AddressInfo;
+    /**
+     * Set the broadcast flag.
+     */
+    setBroadcast(flag: boolean): void;
+    /**
+     * Set the TTL.
+     */
+    setTTL(ttl: number): number;
+    /**
+     * Set multicast TTL.
+     */
+    setMulticastTTL(ttl: number): number;
+    /**
+     * Set multicast loopback.
+     */
+    setMulticastLoopback(flag: boolean): boolean;
+    /**
+     * Add multicast group membership.
+     */
+    addMembership(multicastAddress: string, multicastInterface?: string): void;
+    /**
+     * Drop multicast group membership.
+     */
+    dropMembership(multicastAddress: string, multicastInterface?: string): void;
+    /**
+     * Set multicast interface.
+     */
+    setMulticastInterface(_interfaceAddress: string): void;
+    /** Ref the socket (keep event loop alive). */
+    ref(): this;
+    /** Unref the socket (allow event loop to exit). */
+    unref(): this;
+    /** Get/Set receive buffer size. */
+    getRecvBufferSize(): number;
+    setRecvBufferSize(_size: number): void;
+    /** Get/Set send buffer size. */
+    getSendBufferSize(): number;
+    setSendBufferSize(_size: number): void;
+    /**
+     * Start receiving messages in background.
+     */
+    private _startReceiving;
+    private _receiveLoop;
+}
+/**
+ * Create a UDP socket.
+ */
+export declare function createSocket(type: 'udp4' | 'udp6' | SocketOptions, callback?: (msg: Buffer, rinfo: AddressInfo) => void): Socket;
+declare const _default: {
+    Socket: typeof Socket;
+    createSocket: typeof createSocket;
+};
+export default _default;

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@gjsify/dgram",
+  "version": "0.1.0",
+  "description": "Node.js dgram module for Gjs",
+  "type": "module",
+  "module": "lib/esm/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/esm/index.js"
+    }
+  },
+  "scripts": {
+    "clear": "rm -rf lib tsconfig.tsbuildinfo tsconfig.types.tsbuildinfo test.gjs.mjs test.node.mjs || exit 0",
+    "check": "tsc --noEmit",
+    "build": "yarn build:gjsify && yarn build:types",
+    "build:gjsify": "gjsify build --library 'src/**/*.{ts,js}' --exclude 'src/**/*.spec.{mts,ts}' 'src/test.{mts,ts}'",
+    "build:types": "tsc",
+    "build:test": "yarn build:test:gjs && yarn build:test:node",
+    "build:test:gjs": "gjsify build src/test.mts --app gjs --outfile test.gjs.mjs",
+    "build:test:node": "gjsify build src/test.mts --app node --outfile test.node.mjs",
+    "test": "yarn build:gjsify && yarn build:test && yarn test:node && yarn test:gjs",
+    "test:gjs": "gjs -m test.gjs.mjs",
+    "test:node": "node test.node.mjs"
+  },
+  "keywords": [
+    "gjs",
+    "node",
+    "dgram"
+  ],
+  "dependencies": {
+    "@girs/gio-2.0": "^2.88.0-4.0.0-beta.42",
+    "@girs/glib-2.0": "^2.88.0-4.0.0-beta.42",
+    "@gjsify/buffer": "^0.1.0",
+    "@gjsify/events": "^0.1.0",
+    "@gjsify/utils": "^0.1.0"
+  },
+  "devDependencies": {
+    "@gjsify/cli": "^0.1.0",
+    "@gjsify/unit": "^0.1.0",
+    "@types/node": "^25.5.0",
+    "typescript": "^6.0.2"
+  }
+}