@gjsify/timers 0.1.0

package/README.md

@@ -0,0 +1,29 @@
+# @gjsify/timers
+
+GJS implementation of the Node.js `timers` module. Provides setTimeout, setInterval, setImmediate, and their promises API.
+
+Part of the [gjsify](https://github.com/gjsify/gjsify) project — Node.js and Web APIs for GJS (GNOME JavaScript).
+
+## Installation
+
+```bash
+npm install @gjsify/timers
+# or
+yarn add @gjsify/timers
+```
+
+## Usage
+
+```typescript
+import { setTimeout, setInterval, setImmediate } from '@gjsify/timers';
+import { setTimeout as delay } from '@gjsify/timers/promises';
+
+setTimeout(() => console.log('hello'), 1000);
+
+await delay(1000);
+console.log('1 second later');
+```
+
+## License
+
+MIT

package/lib/esm/index.js

@@ -0,0 +1,52 @@
+import { Timeout, Immediate } from "./timeout.js";
+function _setTimeout(callback, delay = 0, ...args) {
+  return new Timeout(callback, delay, args, false);
+}
+function _clearTimeout(timeout) {
+  if (timeout instanceof Timeout) {
+    timeout.close();
+  } else if (timeout != null) {
+    clearTimeout(timeout);
+  }
+}
+function _setInterval(callback, delay = 0, ...args) {
+  return new Timeout(callback, delay, args, true);
+}
+function _clearInterval(timeout) {
+  if (timeout instanceof Timeout) {
+    timeout.close();
+  } else if (timeout != null) {
+    clearInterval(timeout);
+  }
+}
+function _setImmediate(callback, ...args) {
+  return new Immediate(callback, args);
+}
+function _clearImmediate(immediate) {
+  if (immediate instanceof Immediate) {
+    immediate.close();
+  } else if (immediate != null) {
+    clearTimeout(immediate);
+  }
+}
+var index_default = {
+  setTimeout: _setTimeout,
+  clearTimeout: _clearTimeout,
+  setInterval: _setInterval,
+  clearInterval: _clearInterval,
+  setImmediate: _setImmediate,
+  clearImmediate: _clearImmediate,
+  Timeout,
+  Immediate
+};
+export {
+  Immediate,
+  Timeout,
+  _clearImmediate as clearImmediate,
+  _clearInterval as clearInterval,
+  _clearTimeout as clearTimeout,
+  index_default as default,
+  _setImmediate as setImmediate,
+  _setInterval as setInterval,
+  _setTimeout as setTimeout
+};

package/lib/esm/promises.js

@@ -0,0 +1,65 @@
+import { Timeout } from "./timeout.js";
+function setTimeout(delay = 0, value, options) {
+  return new Promise((resolve, reject) => {
+    if (options?.signal?.aborted) {
+      reject(options.signal.reason ?? new DOMException("The operation was aborted", "AbortError"));
+      return;
+    }
+    const timeout = new Timeout(() => {
+      cleanup();
+      resolve(value);
+    }, delay, [], false);
+    if (options?.ref === false) timeout.unref();
+    let onAbort;
+    function cleanup() {
+      if (onAbort && options?.signal) {
+        options.signal.removeEventListener("abort", onAbort);
+      }
+    }
+    if (options?.signal) {
+      onAbort = () => {
+        timeout.close();
+        reject(options.signal.reason ?? new DOMException("The operation was aborted", "AbortError"));
+      };
+      options.signal.addEventListener("abort", onAbort, { once: true });
+    }
+  });
+}
+function setImmediate(value, options) {
+  return setTimeout(0, value, options);
+}
+async function* setInterval(delay = 0, value, options) {
+  if (options?.signal?.aborted) {
+    throw options.signal.reason ?? new DOMException("The operation was aborted", "AbortError");
+  }
+  while (true) {
+    if (options?.signal?.aborted) {
+      throw options.signal.reason ?? new DOMException("The operation was aborted", "AbortError");
+    }
+    yield await new Promise((resolve, reject) => {
+      const timeout = new Timeout(() => {
+        cleanup();
+        resolve(value);
+      }, delay, [], false);
+      if (options?.ref === false) timeout.unref();
+      let onAbort;
+      function cleanup() {
+        if (onAbort && options?.signal) {
+          options.signal.removeEventListener("abort", onAbort);
+        }
+      }
+      if (options?.signal) {
+        onAbort = () => {
+          timeout.close();
+          reject(options.signal.reason ?? new DOMException("The operation was aborted", "AbortError"));
+        };
+        options.signal.addEventListener("abort", onAbort, { once: true });
+      }
+    });
+  }
+}
+export {
+  setImmediate,
+  setInterval,
+  setTimeout
+};

package/lib/esm/timeout.js

@@ -0,0 +1,106 @@
+class Timeout {
+  _id;
+  _ref = true;
+  _callback;
+  _delay;
+  _args;
+  _isInterval;
+  constructor(callback, delay, args, isInterval) {
+    this._callback = callback;
+    this._delay = delay;
+    this._args = args;
+    this._isInterval = isInterval;
+    if (isInterval) {
+      this._id = setInterval(callback, delay, ...args);
+    } else {
+      this._id = setTimeout(callback, delay, ...args);
+    }
+  }
+  /**
+   * Mark this timeout as referenced (default).
+   * Referenced timers keep the event loop alive.
+   */
+  ref() {
+    this._ref = true;
+    return this;
+  }
+  /**
+   * Mark this timeout as unreferenced.
+   * Unreferenced timers do not keep the event loop alive.
+   */
+  unref() {
+    this._ref = false;
+    return this;
+  }
+  /** Whether this timeout is referenced. */
+  hasRef() {
+    return this._ref;
+  }
+  /**
+   * Reset the timer's start time to now and reschedule.
+   */
+  refresh() {
+    if (this._id != null) {
+      if (this._isInterval) {
+        clearInterval(this._id);
+        this._id = setInterval(this._callback, this._delay, ...this._args);
+      } else {
+        clearTimeout(this._id);
+        this._id = setTimeout(this._callback, this._delay, ...this._args);
+      }
+    }
+    return this;
+  }
+  /** Close/clear this timer. */
+  close() {
+    if (this._id != null) {
+      if (this._isInterval) {
+        clearInterval(this._id);
+      } else {
+        clearTimeout(this._id);
+      }
+      this._id = null;
+    }
+  }
+  /** Get the underlying timer ID (for clearTimeout/clearInterval). */
+  [Symbol.toPrimitive]() {
+    return this._id;
+  }
+}
+class Immediate {
+  _id = null;
+  _ref = true;
+  _cancelled = false;
+  constructor(callback, args) {
+    Promise.resolve().then(() => {
+      if (!this._cancelled) {
+        callback(...args);
+      }
+    });
+  }
+  ref() {
+    this._ref = true;
+    return this;
+  }
+  unref() {
+    this._ref = false;
+    return this;
+  }
+  hasRef() {
+    return this._ref;
+  }
+  close() {
+    this._cancelled = true;
+    if (this._id != null) {
+      clearTimeout(this._id);
+      this._id = null;
+    }
+  }
+  [Symbol.toPrimitive]() {
+    return this._id;
+  }
+}
+export {
+  Immediate,
+  Timeout
+};

package/lib/types/index.d.ts

@@ -0,0 +1,41 @@
+import { Timeout, Immediate } from './timeout.js';
+export { Timeout, Immediate };
+/**
+ * Schedule a callback to be called after `delay` milliseconds.
+ * Returns a Timeout object with ref/unref/refresh methods.
+ */
+declare function _setTimeout<T extends any[]>(callback: (...args: T) => void, delay?: number, ...args: T): Timeout;
+/**
+ * Cancel a timeout created by setTimeout.
+ */
+declare function _clearTimeout(timeout: Timeout | number | undefined): void;
+/**
+ * Schedule a callback to be called repeatedly every `delay` milliseconds.
+ * Returns a Timeout object with ref/unref/refresh methods.
+ */
+declare function _setInterval<T extends any[]>(callback: (...args: T) => void, delay?: number, ...args: T): Timeout;
+/**
+ * Cancel an interval created by setInterval.
+ */
+declare function _clearInterval(timeout: Timeout | number | undefined): void;
+/**
+ * Schedule a callback to be called on the next iteration of the event loop.
+ * Returns an Immediate object with ref/unref methods.
+ */
+declare function _setImmediate<T extends any[]>(callback: (...args: T) => void, ...args: T): Immediate;
+/**
+ * Cancel an immediate created by setImmediate.
+ */
+declare function _clearImmediate(immediate: Immediate | number | undefined): void;
+export { _setTimeout as setTimeout, _clearTimeout as clearTimeout, _setInterval as setInterval, _clearInterval as clearInterval, _setImmediate as setImmediate, _clearImmediate as clearImmediate, };
+declare const _default: {
+    setTimeout: typeof _setTimeout;
+    clearTimeout: typeof _clearTimeout;
+    setInterval: typeof _setInterval;
+    clearInterval: typeof _clearInterval;
+    setImmediate: typeof _setImmediate;
+    clearImmediate: typeof _clearImmediate;
+    Timeout: typeof Timeout;
+    Immediate: typeof Immediate;
+};
+export default _default;

package/lib/types/promises.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Returns a promise that resolves after `delay` milliseconds.
+ * Supports AbortSignal for cancellation.
+ */
+export declare function setTimeout<T = void>(delay?: number, value?: T, options?: {
+    signal?: AbortSignal;
+    ref?: boolean;
+}): Promise<T>;
+/**
+ * Returns a promise that resolves on the next event loop iteration.
+ * Supports AbortSignal for cancellation.
+ */
+export declare function setImmediate<T = void>(value?: T, options?: {
+    signal?: AbortSignal;
+    ref?: boolean;
+}): Promise<T>;
+/**
+ * Returns an async iterable that yields at `delay` ms intervals.
+ * Supports AbortSignal for cancellation.
+ */
+export declare function setInterval<T = void>(delay?: number, value?: T, options?: {
+    signal?: AbortSignal;
+    ref?: boolean;
+}): AsyncGenerator<T>;

package/lib/types/timeout.d.ts

@@ -0,0 +1,40 @@
+export declare class Timeout {
+    private _id;
+    private _ref;
+    private _callback;
+    private _delay;
+    private _args;
+    private _isInterval;
+    constructor(callback: (...args: any[]) => void, delay: number, args: any[], isInterval: boolean);
+    /**
+     * Mark this timeout as referenced (default).
+     * Referenced timers keep the event loop alive.
+     */
+    ref(): this;
+    /**
+     * Mark this timeout as unreferenced.
+     * Unreferenced timers do not keep the event loop alive.
+     */
+    unref(): this;
+    /** Whether this timeout is referenced. */
+    hasRef(): boolean;
+    /**
+     * Reset the timer's start time to now and reschedule.
+     */
+    refresh(): this;
+    /** Close/clear this timer. */
+    close(): void;
+    /** Get the underlying timer ID (for clearTimeout/clearInterval). */
+    [Symbol.toPrimitive](): number;
+}
+export declare class Immediate {
+    private _id;
+    private _ref;
+    private _cancelled;
+    constructor(callback: (...args: any[]) => void, args: any[]);
+    ref(): this;
+    unref(): this;
+    hasRef(): boolean;
+    close(): void;
+    [Symbol.toPrimitive](): number;
+}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@gjsify/timers",
+  "version": "0.1.0",
+  "description": "Node.js timers 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"
+    },
+    "./promises": {
+      "types": "./lib/types/promises.d.ts",
+      "default": "./lib/esm/promises.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",
+    "timers"
+  ],
+  "devDependencies": {
+    "@gjsify/cli": "^0.1.0",
+    "@gjsify/unit": "^0.1.0",
+    "@types/node": "^25.5.0",
+    "typescript": "^6.0.2"
+  }
+}

package/src/extended.spec.ts

@@ -0,0 +1,149 @@
+// Ported from refs/node-test/parallel/test-timers-*.js
+// Original: MIT license, Node.js contributors
+
+import { describe, it, expect } from '@gjsify/unit';
+
+export default async () => {
+
+  // ===================== setTimeout deep =====================
+  await describe('setTimeout deep', async () => {
+    await it('should call callback after delay', async () => {
+      const start = Date.now();
+      await new Promise<void>((resolve) => {
+        setTimeout(() => {
+          const elapsed = Date.now() - start;
+          expect(elapsed >= 20).toBe(true);
+          resolve();
+        }, 30);
+      });
+    });
+
+    await it('should pass arguments to callback', async () => {
+      const result = await new Promise<string>((resolve) => {
+        setTimeout((a: string, b: string) => resolve(a + b), 10, 'hello', ' world');
+      });
+      expect(result).toBe('hello world');
+    });
+
+    await it('should return a timeout ID', async () => {
+      const id = setTimeout(() => {}, 1000);
+      expect(id).toBeDefined();
+      clearTimeout(id);
+    });
+
+    await it('clearTimeout should prevent callback', async () => {
+      let called = false;
+      const id = setTimeout(() => { called = true; }, 30);
+      clearTimeout(id);
+      await new Promise<void>((r) => setTimeout(r, 100));
+      expect(called).toBe(false);
+    });
+
+    await it('should handle 0 delay', async () => {
+      const result = await new Promise<boolean>((resolve) => {
+        setTimeout(() => resolve(true), 0);
+      });
+      expect(result).toBe(true);
+    });
+  });
+
+  // ===================== setInterval deep =====================
+  await describe('setInterval deep', async () => {
+    await it('should call callback repeatedly', async () => {
+      let count = 0;
+      await new Promise<void>((resolve) => {
+        const id = setInterval(() => {
+          count++;
+          if (count >= 3) {
+            clearInterval(id);
+            resolve();
+          }
+        }, 30);
+      });
+      expect(count).toBeGreaterThan(2);
+    });
+
+    await it('clearInterval should stop repetition', async () => {
+      let count = 0;
+      const id = setInterval(() => { count++; }, 20);
+      await new Promise<void>((r) => setTimeout(r, 60));
+      clearInterval(id);
+      const countAfterClear = count;
+      await new Promise<void>((r) => setTimeout(r, 60));
+      // Should not have increased much after clear
+      expect(count - countAfterClear).toBeLessThan(2);
+    });
+
+    await it('should pass arguments to callback', async () => {
+      const result = await new Promise<number>((resolve) => {
+        const id = setInterval((val: number) => {
+          clearInterval(id);
+          resolve(val);
+        }, 10, 42);
+      });
+      expect(result).toBe(42);
+    });
+  });
+
+  // ===================== setImmediate =====================
+  await describe('setImmediate', async () => {
+    await it('should call callback asynchronously', async () => {
+      let called = false;
+      setImmediate(() => { called = true; });
+      expect(called).toBe(false); // Should not be called synchronously
+      await new Promise<void>((r) => setTimeout(r, 50));
+      expect(called).toBe(true);
+    });
+
+    await it('should pass arguments', async () => {
+      const result = await new Promise<string>((resolve) => {
+        setImmediate((a: string) => resolve(a), 'immediate');
+      });
+      expect(result).toBe('immediate');
+    });
+
+    await it('clearImmediate should prevent callback', async () => {
+      let called = false;
+      const id = setImmediate(() => { called = true; });
+      clearImmediate(id);
+      await new Promise<void>((r) => setTimeout(r, 50));
+      expect(called).toBe(false);
+    });
+  });
+
+  // ===================== Ordering guarantees =====================
+  await describe('timer ordering', async () => {
+    await it('setImmediate should fire before setTimeout(0)', async () => {
+      const order: string[] = [];
+      await new Promise<void>((resolve) => {
+        setTimeout(() => {
+          order.push('timeout');
+          if (order.length === 2) resolve();
+        }, 0);
+        setImmediate(() => {
+          order.push('immediate');
+          if (order.length === 2) resolve();
+        });
+      });
+      // Both should have fired
+      expect(order.length).toBe(2);
+      expect(order).toContain('timeout');
+      expect(order).toContain('immediate');
+    });
+
+    await it('nested setTimeout should fire in order', async () => {
+      const order: number[] = [];
+      await new Promise<void>((resolve) => {
+        setTimeout(() => {
+          order.push(1);
+          setTimeout(() => {
+            order.push(2);
+            resolve();
+          }, 10);
+        }, 10);
+      });
+      expect(order[0]).toBe(1);
+      expect(order[1]).toBe(2);
+    });
+  });
+};