@gjsify/timers 0.53.0 → 0.54.0

package/README.md

@@ -26,6 +26,45 @@ await delay(1000);
 console.log('1 second later');
 ```
 
+## The returned handle is Node-compatible
+
+`setTimeout` / `setInterval` return a handle carrying the full `NodeJS.Timeout`
+surface, so the cast third-party code used to need is gone:
+
+```typescript
+const sweep = setInterval(() => rooms.sweep(), 30_000);
+sweep.unref();            // no cast, no `as unknown as { unref?: () => void }`
+sweep.hasRef();           // → boolean
+sweep.refresh();          // reschedule from now, returns the same handle
+clearInterval(sweep);     // or `sweep.close()`, or `+sweep` for the numeric ID
+```
+
+Members: `ref()`, `unref()`, `hasRef()`, `refresh()`, `close()`,
+`[Symbol.toPrimitive]()` (→ the numeric timer ID, for libraries that key a Map
+on it), `[Symbol.dispose]()` and `_onTimeout()` (what `@types/node` declares, and
+what libraries call directly when they drive a handle themselves).
+`clearTimeout` / `clearInterval` accept the handle itself, a foreign Node
+handle, or a bare number — the check is structural, so it survives a duplicated
+copy of this module in a bundle.
+
+### What `unref()` means on GJS
+
+**On Node, `unref()` really releases the event loop** and the process may exit
+while the timer is pending. On GJS it **cannot**, and this package does not
+pretend otherwise:
+
+- `Gtk.Application` / `GLib.MainLoop` own the loop — not the JS heap. Nothing a
+  timer does decides whether the app keeps running.
+- The only GLib operation that releases a source's hold on the loop
+  (`g_source_unref`) also destroys the source. That is the double-unref
+  SIGSEGV this package exists to avoid, so the timers are backed by
+  `GLib.timeout_add` and numeric source IDs for exactly this reason.
+
+So on GJS `unref()` is **recorded and reported**: `hasRef()` returns `false`
+after it, and the timer keeps firing. Code that calls `unref()` to mean "don't
+let this timer hold my process open" is correct on both runtimes — it simply
+has no work to do on GJS, because the app, not the timer, decides that.
+
 ## License
 
 MIT

package/lib/esm/index.js

@@ -1 +1 @@
-import"./_virtual/_rolldown/runtime.js";import{Immediate as e,Timeout as t}from"./timeout.js";function _setTimeout(e,n=0,...r){return new t(e,n,r,!1)}function _clearTimeout(e){e instanceof t?e.close():e!=null&&clearTimeout(e)}function _setInterval(e,n=0,...r){return new t(e,n,r,!0)}function _clearInterval(e){e instanceof t?e.close():e!=null&&clearInterval(e)}function _setImmediate(t,...n){return new e(t,n)}function _clearImmediate(t){t instanceof e?t.close():t!=null&&clearTimeout(t)}var n={setTimeout:_setTimeout,clearTimeout:_clearTimeout,setInterval:_setInterval,clearInterval:_clearInterval,setImmediate:_setImmediate,clearImmediate:_clearImmediate,Timeout:t,Immediate:e};export{e as Immediate,t as Timeout,_clearImmediate as clearImmediate,_clearInterval as clearInterval,_clearTimeout as clearTimeout,n as default,_setImmediate as setImmediate,_setInterval as setInterval,_setTimeout as setTimeout};
+import"./_virtual/_rolldown/runtime.js";import{Immediate as e,Timeout as t}from"./timeout.js";function isNodeTimerHandle(e){if(typeof e!=`object`||!e)return!1;let t=e;return typeof t.unref==`function`&&typeof t.hasRef==`function`&&typeof t.close==`function`}function _clearTimeout(e){isNodeTimerHandle(e)?e.close():e!=null&&clearTimeout(e)}function _setTimeout(e,n=0,...r){return new t(e,n,r,!1)}function _setInterval(e,n=0,...r){return new t(e,n,r,!0)}function _clearInterval(e){isNodeTimerHandle(e)?e.close():e!=null&&clearInterval(e)}function _setImmediate(t,...n){return new e(t,n)}function _clearImmediate(e){isNodeTimerHandle(e)?e.close():e!=null&&clearTimeout(e)}var n={setTimeout:_setTimeout,clearTimeout:_clearTimeout,setInterval:_setInterval,clearInterval:_clearInterval,setImmediate:_setImmediate,clearImmediate:_clearImmediate,Timeout:t,Immediate:e};export{e as Immediate,t as Timeout,_clearImmediate as clearImmediate,_clearInterval as clearInterval,_clearTimeout as clearTimeout,n as default,_setImmediate as setImmediate,_setInterval as setInterval,_setTimeout as setTimeout};

package/lib/esm/timeout.js

@@ -1 +1 @@
-import"./_virtual/_rolldown/runtime.js";var Timeout=class{_id;_ref=!0;_callback;_delay;_args;_isInterval;constructor(e,t,n,r){this._callback=e,this._delay=t,this._args=n,this._isInterval=r,r?this._id=setInterval(e,t,...n):this._id=setTimeout(e,t,...n)}ref(){return this._ref=!0,this}unref(){return this._ref=!1,this}hasRef(){return this._ref}refresh(){return this._id!=null&&(this._isInterval?(clearInterval(this._id),this._id=setInterval(this._callback,this._delay,...this._args)):(clearTimeout(this._id),this._id=setTimeout(this._callback,this._delay,...this._args))),this}close(){this._id!=null&&(this._isInterval?clearInterval(this._id):clearTimeout(this._id),this._id=null)}[Symbol.toPrimitive](){return this._id}},Immediate=class{_id=null;_ref=!0;_cancelled=!1;constructor(e,t){Promise.resolve().then(()=>{this._cancelled||e(...t)})}ref(){return this._ref=!0,this}unref(){return this._ref=!1,this}hasRef(){return this._ref}close(){this._cancelled=!0,this._id!=null&&(clearTimeout(this._id),this._id=null)}[Symbol.toPrimitive](){return this._id}};export{Immediate,Timeout};
+import"./_virtual/_rolldown/runtime.js";function canDelegateRef(e){if(typeof e!=`object`||!e)return!1;let t=e;return typeof t.unref==`function`&&typeof t.ref==`function`&&typeof t.hasRef==`function`&&typeof t.refresh==`function`}var Timeout=class{_id;_ref=!0;_callback;_delay;_args;_isInterval;_numericId;constructor(e,t,n,r){this._callback=e,this._delay=t,this._args=n,this._isInterval=r,r?this._id=setInterval(e,t,...n):this._id=setTimeout(e,t,...n),this._numericId=Number(this._id)}ref(){return this._ref=!0,this._id!=null&&canDelegateRef(this._id)&&this._id.ref(),this}unref(){return this._ref=!1,this._id!=null&&canDelegateRef(this._id)&&this._id.unref(),this}hasRef(){return this._ref}refresh(){return this._id!=null&&(this._isInterval?(clearInterval(this._id),this._id=setInterval(this._callback,this._delay,...this._args)):(clearTimeout(this._id),this._id=setTimeout(this._callback,this._delay,...this._args)),this._numericId=Number(this._id),!this._ref&&canDelegateRef(this._id)&&this._id.unref()),this}close(){return this._id!=null&&(this._isInterval?clearInterval(this._id):clearTimeout(this._id),this._id=null),this}_onTimeout(...e){this._callback(...e)}[Symbol.dispose](){this.close()}[Symbol.toPrimitive](){return this._numericId}},Immediate=class{_cancelled=!1;_ref=!0;_callback;_args;constructor(e,t){this._callback=e,this._args=t,Promise.resolve().then(()=>{this._cancelled||this._onImmediate(...this._args)})}ref(){return this._ref=!0,this}unref(){return this._ref=!1,this}hasRef(){return this._ref}close(){return this._cancelled=!0,this}_onImmediate(...e){this._callback(...e)}[Symbol.dispose](){this.close()}};export{Immediate,Timeout};

package/lib/types/index.d.ts

@@ -1,32 +1,72 @@
 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.
+ * Structural shape of a Node timer handle, as `@types/node` declares it for
+ * `NodeJS.Timeout`.
+ *
+ * This is what makes the return value usable WITHOUT a cast: a consumer's
+ * `setInterval(...).unref()` type-checks because the object we return satisfies
+ * this interface, which is why the globals register path and this module agree
+ * on the same members.
+ *
+ * `close(): unknown` because `@types/node` declares `close(): void` while ours
+ * returns `this` for chaining — a `this` return satisfies a `void` one.
  */
-declare function _setTimeout<T extends unknown[]>(callback: (...args: T) => void, delay?: number, ...args: T): Timeout;
+export interface NodeTimerHandle {
+    ref(): unknown;
+    unref(): unknown;
+    hasRef(): boolean;
+    refresh(): unknown;
+    close(): unknown;
+    [Symbol.toPrimitive](): number;
+    [Symbol.dispose](): void;
+}
+/** A Node `Immediate` has no `refresh`/`toPrimitive`, so it gets its own shape. */
+export interface NodeImmediateHandle {
+    ref(): unknown;
+    unref(): unknown;
+    hasRef(): boolean;
+    [Symbol.dispose](): void;
+}
 /**
  * Cancel a timeout created by setTimeout.
+ *
+ * Accepts the Node spellings, not just our own instance: `setTimeout` may have
+ * come from a third-party module, from a `worker_threads` realm, or as a bare
+ * number (a browser handle). Anything with the `unref`/`hasRef`/`close` trio is
+ * structurally a Node `Timeout`, so duck-type it rather than `instanceof` — the
+ * check has to survive a duplicate copy of this module in the bundle, which is
+ * exactly the situation that made consumers cast in the first place.
+ */
+declare function _clearTimeout(timeout: NodeTimerHandle | number | undefined): void;
+/**
+ * Schedule a callback to be called after `delay` milliseconds.
+ *
+ * The returned handle satisfies {@link NodeTimerHandle}, so a consumer typed
+ * against `@types/node` calls `.unref()` on it without a cast.
  */
-declare function _clearTimeout(timeout: Timeout | number | undefined): void;
+declare function _setTimeout<T extends unknown[]>(callback: (...args: T) => void, delay?: number, ...args: T): Timeout;
 /**
  * Schedule a callback to be called repeatedly every `delay` milliseconds.
- * Returns a Timeout object with ref/unref/refresh methods.
+ * Returns the same handle shape as {@link _setTimeout}.
  */
 declare function _setInterval<T extends unknown[]>(callback: (...args: T) => void, delay?: number, ...args: T): Timeout;
 /**
- * Cancel an interval created by setInterval.
+ * Cancel an interval created by setInterval. Accepts the same shapes as
+ * {@link _clearTimeout}.
  */
-declare function _clearInterval(timeout: Timeout | number | undefined): void;
+declare function _clearInterval(timeout: NodeTimerHandle | 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 unknown[]>(callback: (...args: T) => void, ...args: T): Immediate;
 /**
- * Cancel an immediate created by setImmediate.
+ * Cancel an immediate created by setImmediate. Accepts a foreign Node `Immediate`
+ * through the same duck-type as {@link _clearTimeout}, because `instanceof` fails
+ * across a duplicated module and callers hold whatever `setImmediate` gave them.
  */
-declare function _clearImmediate(immediate: Immediate | number | undefined): void;
+declare function _clearImmediate(immediate: Immediate | NodeImmediateHandle | 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;

package/lib/types/timeout.d.ts

@@ -1,3 +1,4 @@
+type TimerCallback = (...args: unknown[]) => void;
 export declare class Timeout {
     private _id;
     private _ref;
@@ -5,36 +6,70 @@ export declare class Timeout {
     private _delay;
     private _args;
     private _isInterval;
-    constructor(callback: (...args: unknown[]) => void, delay: number, args: unknown[], isInterval: boolean);
+    /**
+     * Retained so `+timeout` still yields a number after `close()`, where the
+     * host handle is gone. Node keeps its id readable for the object's life.
+     */
+    private _numericId;
+    constructor(callback: TimerCallback, delay: number, args: unknown[], isInterval: boolean);
     /**
      * Mark this timeout as referenced (default).
-     * Referenced timers keep the event loop alive.
+     *
+     * Delegated to the host where the host is a Node-shaped handle (see
+     * {@link canDelegateRef}); recorded only otherwise.
      */
     ref(): this;
     /**
-     * Mark this timeout as unreferenced.
-     * Unreferenced timers do not keep the event loop alive.
+     * Mark this timeout as unreferenced — the caller asks that it not require
+     * the host loop to stay alive.
+     *
+     * Honoured on Node (delegated to libuv). On GJS it is RECORDED ONLY and the
+     * timer keeps firing: the app owns the main loop, and releasing liveness
+     * there would mean destroying the GLib source. `hasRef()` reports the
+     * recorded flag on both runtimes.
      */
     unref(): this;
     /** Whether this timeout is referenced. */
     hasRef(): boolean;
     /**
      * Reset the timer's start time to now and reschedule.
+     *
+     * The ref state is carried over: rescheduling creates a NEW host handle,
+     * which arrives refed, so an `unref()`ed timer that is refreshed would
+     * silently start holding the event loop open again — on Node that is the
+     * difference between a process that exits and one that hangs.
      */
     refresh(): this;
-    /** Close/clear this timer. */
-    close(): void;
+    /** Close/clear this timer. Returns `this`, matching `@types/node`. */
+    close(): this;
+    /**
+     * Node libraries call this directly rather than going through the scheduled
+     * dispatch (`@types/node` declares it on `NodeJS.Timeout`).
+     */
+    _onTimeout(...args: unknown[]): void;
+    [Symbol.dispose](): 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: unknown[]) => void, args: unknown[]);
+    private _ref;
+    readonly _callback: TimerCallback;
+    readonly _args: unknown[];
+    constructor(callback: TimerCallback, args: unknown[]);
+    /**
+     * Recorded only, never delegated — an `Immediate` here is a microtask, not a
+     * host handle, so there is nothing to release. See {@link Timeout.unref} for
+     * why that is the honest answer on GJS.
+     */
     ref(): this;
+    /** Recorded only — see {@link Timeout.unref}. */
     unref(): this;
     hasRef(): boolean;
-    close(): void;
-    [Symbol.toPrimitive](): number;
+    /** Cancels the immediate. Returns `this` for the same reason `Timeout.close` does. */
+    close(): this;
+    /** Node libraries call this directly (`@types/node` declares it). */
+    _onImmediate(...args: unknown[]): void;
+    [Symbol.dispose](): void;
 }
+export {};

package/lib/types/timeout.gjs.spec.d.ts

@@ -0,0 +1,2 @@
+declare const _default: () => Promise<void>;
+export default _default;

package/lib/types/timeout.spec.d.ts

@@ -0,0 +1,2 @@
+declare const _default: () => Promise<void>;
+export default _default;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gjsify/timers",
-    "version": "0.53.0",
+    "version": "0.54.0",
     "description": "Node.js timers module for Gjs",
     "type": "module",
     "module": "lib/esm/index.js",
@@ -40,8 +40,8 @@
         "timers"
     ],
     "devDependencies": {
-        "@gjsify/cli": "^0.53.0",
-        "@gjsify/unit": "^0.53.0",
+        "@gjsify/cli": "^0.54.0",
+        "@gjsify/unit": "^0.54.0",
         "@types/node": "^25.9.2",
         "typescript": "^6.0.3"
     },