@gjsify/diagnostics_channel 0.1.0

package/README.md

@@ -0,0 +1,29 @@
+# @gjsify/diagnostics_channel
+
+GJS implementation of the Node.js `diagnostics_channel` module. Provides Channel and TracingChannel.
+
+Part of the [gjsify](https://github.com/gjsify/gjsify) project — Node.js and Web APIs for GJS (GNOME JavaScript).
+
+## Installation
+
+```bash
+npm install @gjsify/diagnostics_channel
+# or
+yarn add @gjsify/diagnostics_channel
+```
+
+## Usage
+
+```typescript
+import { channel } from '@gjsify/diagnostics_channel';
+
+const ch = channel('my-channel');
+ch.subscribe((message) => {
+  console.log('Received:', message);
+});
+ch.publish({ data: 'hello' });
+```
+
+## License
+
+MIT

package/lib/esm/index.js

@@ -0,0 +1,263 @@
+const channels = /* @__PURE__ */ new Map();
+class Channel {
+  name;
+  _subscribers = [];
+  constructor(name) {
+    this.name = name;
+  }
+  /** Whether this channel has active subscribers. */
+  get hasSubscribers() {
+    return this._subscribers.length > 0;
+  }
+  /**
+   * Publish a message to all subscribers.
+   * Subscriber errors are caught and re-thrown asynchronously so that
+   * remaining subscribers still run (matches Node.js behavior).
+   */
+  publish(message) {
+    if (this._subscribers.length === 0) return;
+    const subscribers = this._subscribers;
+    for (let i = 0; i < subscribers.length; i++) {
+      try {
+        subscribers[i](message, this.name);
+      } catch (err) {
+        Promise.resolve().then(() => {
+          throw err;
+        });
+      }
+    }
+  }
+  /** Subscribe to this channel. */
+  subscribe(onMessage) {
+    if (typeof onMessage !== "function") {
+      throw new TypeError('The "subscription" argument must be of type function');
+    }
+    this._subscribers = [...this._subscribers, onMessage];
+  }
+  /** Unsubscribe from this channel. Returns true if the subscriber was found. */
+  unsubscribe(onMessage) {
+    const index = this._subscribers.indexOf(onMessage);
+    if (index === -1) return false;
+    this._subscribers = [
+      ...this._subscribers.slice(0, index),
+      ...this._subscribers.slice(index + 1)
+    ];
+    return true;
+  }
+  /**
+   * Run stores and publish (simplified — no AsyncLocalStorage store support yet).
+   * Publishes the data and calls fn with the given thisArg and args.
+   */
+  runStores(data, fn, thisArg, ...args) {
+    this.publish(data);
+    return fn.apply(thisArg, args);
+  }
+  /** Bind a store to this channel (stub — AsyncLocalStorage integration). */
+  bindStore(_store, _transform) {
+  }
+  /** Unbind a store from this channel (stub). */
+  unbindStore(_store) {
+  }
+}
+function channel(name) {
+  if (typeof name !== "string" && typeof name !== "symbol") {
+    throw new TypeError('The "channel" argument must be of type string or symbol');
+  }
+  let ch = channels.get(name);
+  if (!ch) {
+    ch = new Channel(name);
+    channels.set(name, ch);
+  }
+  return ch;
+}
+function hasSubscribers(name) {
+  const ch = channels.get(name);
+  return ch ? ch.hasSubscribers : false;
+}
+function subscribe(name, onMessage) {
+  channel(name).subscribe(onMessage);
+}
+function unsubscribe(name, onMessage) {
+  return channel(name).unsubscribe(onMessage);
+}
+class TracingChannel {
+  start;
+  end;
+  asyncStart;
+  asyncEnd;
+  error;
+  constructor(nameOrChannels) {
+    if (typeof nameOrChannels === "string") {
+      const name = nameOrChannels;
+      this.start = channel(`tracing:${name}:start`);
+      this.end = channel(`tracing:${name}:end`);
+      this.asyncStart = channel(`tracing:${name}:asyncStart`);
+      this.asyncEnd = channel(`tracing:${name}:asyncEnd`);
+      this.error = channel(`tracing:${name}:error`);
+    } else if (typeof nameOrChannels === "object" && nameOrChannels !== null) {
+      const traceEvents = ["start", "end", "asyncStart", "asyncEnd", "error"];
+      for (const eventName of traceEvents) {
+        const ch = nameOrChannels[eventName];
+        if (!(ch instanceof Channel)) {
+          throw new TypeError(
+            `The "nameOrChannels.${eventName}" property must be an instance of Channel`
+          );
+        }
+      }
+      this.start = nameOrChannels.start;
+      this.end = nameOrChannels.end;
+      this.asyncStart = nameOrChannels.asyncStart;
+      this.asyncEnd = nameOrChannels.asyncEnd;
+      this.error = nameOrChannels.error;
+    } else {
+      throw new TypeError(
+        'The "nameOrChannels" argument must be of type string or an instance of TracingChannel or Object'
+      );
+    }
+  }
+  /** Whether any of the tracing sub-channels has subscribers. */
+  get hasSubscribers() {
+    return this.start.hasSubscribers || this.end.hasSubscribers || this.asyncStart.hasSubscribers || this.asyncEnd.hasSubscribers || this.error.hasSubscribers;
+  }
+  /** Subscribe to all tracing channels. */
+  subscribe(handlers) {
+    if (handlers.start) this.start.subscribe(handlers.start);
+    if (handlers.end) this.end.subscribe(handlers.end);
+    if (handlers.asyncStart) this.asyncStart.subscribe(handlers.asyncStart);
+    if (handlers.asyncEnd) this.asyncEnd.subscribe(handlers.asyncEnd);
+    if (handlers.error) this.error.subscribe(handlers.error);
+  }
+  /** Unsubscribe from all tracing channels. Returns true if all were found. */
+  unsubscribe(handlers) {
+    let done = true;
+    if (handlers.start && !this.start.unsubscribe(handlers.start)) done = false;
+    if (handlers.end && !this.end.unsubscribe(handlers.end)) done = false;
+    if (handlers.asyncStart && !this.asyncStart.unsubscribe(handlers.asyncStart)) done = false;
+    if (handlers.asyncEnd && !this.asyncEnd.unsubscribe(handlers.asyncEnd)) done = false;
+    if (handlers.error && !this.error.unsubscribe(handlers.error)) done = false;
+    return done;
+  }
+  /**
+   * Execute a function within a tracing context.
+   * Matches Node.js signature: traceSync(fn, context, thisArg, ...args)
+   */
+  traceSync(fn, context = {}, thisArg, ...args) {
+    if (!this.hasSubscribers) {
+      return fn.apply(thisArg, args);
+    }
+    const { start, end, error } = this;
+    start.publish(context);
+    try {
+      const result = fn.apply(thisArg, args);
+      context.result = result;
+      return result;
+    } catch (err) {
+      context.error = err;
+      error.publish(context);
+      throw err;
+    } finally {
+      end.publish(context);
+    }
+  }
+  /**
+   * Execute an async function within a tracing context.
+   * Matches Node.js signature: tracePromise(fn, context, thisArg, ...args)
+   */
+  tracePromise(fn, context = {}, thisArg, ...args) {
+    if (!this.hasSubscribers) {
+      return fn.apply(thisArg, args);
+    }
+    const { start, end, asyncStart, asyncEnd, error } = this;
+    function resolve(result) {
+      context.result = result;
+      asyncStart.publish(context);
+      asyncEnd.publish(context);
+      return result;
+    }
+    function reject(err) {
+      context.error = err;
+      error.publish(context);
+      asyncStart.publish(context);
+      asyncEnd.publish(context);
+      throw err;
+    }
+    start.publish(context);
+    try {
+      const result = fn.apply(thisArg, args);
+      if (typeof result?.then !== "function") {
+        context.result = result;
+        return result;
+      }
+      return result.then(resolve, reject);
+    } catch (err) {
+      context.error = err;
+      error.publish(context);
+      throw err;
+    } finally {
+      end.publish(context);
+    }
+  }
+  /**
+   * Execute a callback-style function within a tracing context.
+   * Matches Node.js signature: traceCallback(fn, position, context, thisArg, ...args)
+   */
+  traceCallback(fn, position = -1, context = {}, thisArg, ...args) {
+    if (!this.hasSubscribers) {
+      return fn.apply(thisArg, args);
+    }
+    const { start, end, asyncStart, asyncEnd, error } = this;
+    const actualPos = position < 0 ? args.length + position : position;
+    const callback = args[actualPos];
+    if (typeof callback !== "function") {
+      throw new TypeError('The "callback" argument must be of type function');
+    }
+    function wrappedCallback(err, res) {
+      if (err) {
+        context.error = err;
+        error.publish(context);
+      } else {
+        context.result = res;
+      }
+      asyncStart.publish(context);
+      try {
+        return callback.apply(this, arguments);
+      } finally {
+        asyncEnd.publish(context);
+      }
+    }
+    const wrappedArgs = [...args];
+    wrappedArgs[actualPos] = wrappedCallback;
+    start.publish(context);
+    try {
+      return fn.apply(thisArg, wrappedArgs);
+    } catch (err) {
+      context.error = err;
+      error.publish(context);
+      throw err;
+    } finally {
+      end.publish(context);
+    }
+  }
+}
+function tracingChannel(nameOrChannels) {
+  return new TracingChannel(nameOrChannels);
+}
+var index_default = {
+  Channel,
+  channel,
+  hasSubscribers,
+  subscribe,
+  unsubscribe,
+  TracingChannel,
+  tracingChannel
+};
+export {
+  Channel,
+  TracingChannel,
+  channel,
+  index_default as default,
+  hasSubscribers,
+  subscribe,
+  tracingChannel,
+  unsubscribe
+};

package/lib/types/index.d.ts

@@ -0,0 +1,116 @@
+type MessageHandler = (message: unknown, name: string | symbol) => void;
+/**
+ * A named channel for publishing diagnostic messages.
+ */
+export declare class Channel {
+    readonly name: string | symbol;
+    private _subscribers;
+    constructor(name: string | symbol);
+    /** Whether this channel has active subscribers. */
+    get hasSubscribers(): boolean;
+    /**
+     * Publish a message to all subscribers.
+     * Subscriber errors are caught and re-thrown asynchronously so that
+     * remaining subscribers still run (matches Node.js behavior).
+     */
+    publish(message: unknown): void;
+    /** Subscribe to this channel. */
+    subscribe(onMessage: MessageHandler): void;
+    /** Unsubscribe from this channel. Returns true if the subscriber was found. */
+    unsubscribe(onMessage: MessageHandler): boolean;
+    /**
+     * Run stores and publish (simplified — no AsyncLocalStorage store support yet).
+     * Publishes the data and calls fn with the given thisArg and args.
+     */
+    runStores(data: unknown, fn: (...args: unknown[]) => unknown, thisArg?: unknown, ...args: unknown[]): unknown;
+    /** Bind a store to this channel (stub — AsyncLocalStorage integration). */
+    bindStore(_store: unknown, _transform?: (message: unknown) => unknown): void;
+    /** Unbind a store from this channel (stub). */
+    unbindStore(_store: unknown): void;
+}
+/**
+ * Get or create a named channel.
+ */
+export declare function channel(name: string | symbol): Channel;
+/**
+ * Check if the named channel has subscribers.
+ */
+export declare function hasSubscribers(name: string | symbol): boolean;
+/**
+ * Subscribe to a named channel.
+ */
+export declare function subscribe(name: string | symbol, onMessage: MessageHandler): void;
+/**
+ * Unsubscribe from a named channel.
+ */
+export declare function unsubscribe(name: string | symbol, onMessage: MessageHandler): boolean;
+/**
+ * TracingChannel — groups related channels for start/end/asyncStart/asyncEnd/error.
+ */
+export declare class TracingChannel {
+    readonly start: Channel;
+    readonly end: Channel;
+    readonly asyncStart: Channel;
+    readonly asyncEnd: Channel;
+    readonly error: Channel;
+    constructor(nameOrChannels: string | {
+        start: Channel;
+        end: Channel;
+        asyncStart: Channel;
+        asyncEnd: Channel;
+        error: Channel;
+    });
+    /** Whether any of the tracing sub-channels has subscribers. */
+    get hasSubscribers(): boolean;
+    /** Subscribe to all tracing channels. */
+    subscribe(handlers: {
+        start?: MessageHandler;
+        end?: MessageHandler;
+        asyncStart?: MessageHandler;
+        asyncEnd?: MessageHandler;
+        error?: MessageHandler;
+    }): void;
+    /** Unsubscribe from all tracing channels. Returns true if all were found. */
+    unsubscribe(handlers: {
+        start?: MessageHandler;
+        end?: MessageHandler;
+        asyncStart?: MessageHandler;
+        asyncEnd?: MessageHandler;
+        error?: MessageHandler;
+    }): boolean;
+    /**
+     * Execute a function within a tracing context.
+     * Matches Node.js signature: traceSync(fn, context, thisArg, ...args)
+     */
+    traceSync(fn: (...args: unknown[]) => unknown, context?: Record<string, unknown>, thisArg?: unknown, ...args: unknown[]): unknown;
+    /**
+     * Execute an async function within a tracing context.
+     * Matches Node.js signature: tracePromise(fn, context, thisArg, ...args)
+     */
+    tracePromise(fn: (...args: unknown[]) => unknown, context?: Record<string, unknown>, thisArg?: unknown, ...args: unknown[]): unknown;
+    /**
+     * Execute a callback-style function within a tracing context.
+     * Matches Node.js signature: traceCallback(fn, position, context, thisArg, ...args)
+     */
+    traceCallback(fn: (...args: unknown[]) => unknown, position?: number, context?: Record<string, unknown>, thisArg?: unknown, ...args: unknown[]): unknown;
+}
+/**
+ * Create a TracingChannel instance.
+ */
+export declare function tracingChannel(nameOrChannels: string | {
+    start: Channel;
+    end: Channel;
+    asyncStart: Channel;
+    asyncEnd: Channel;
+    error: Channel;
+}): TracingChannel;
+declare const _default: {
+    Channel: typeof Channel;
+    channel: typeof channel;
+    hasSubscribers: typeof hasSubscribers;
+    subscribe: typeof subscribe;
+    unsubscribe: typeof unsubscribe;
+    TracingChannel: typeof TracingChannel;
+    tracingChannel: typeof tracingChannel;
+};
+export default _default;

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@gjsify/diagnostics_channel",
+  "version": "0.1.0",
+  "description": "Node.js diagnostics_channel 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",
+    "diagnostics_channel"
+  ],
+  "devDependencies": {
+    "@gjsify/cli": "^0.1.0",
+    "@gjsify/unit": "^0.1.0",
+    "@types/node": "^25.5.0",
+    "typescript": "^6.0.2"
+  }
+}