@nxtedition/timers 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) nxtedition
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,111 @@
+# @nxtedition/timers
+
+Optimized timer pooling for Node.js. Delays >= 1000ms are batched into a single 500ms-resolution interval, reducing the number of active handles and improving performance when many long-lived timers are in use.
+
+Short delays (< 1000ms) fall through to the native `setTimeout` for full resolution.
+
+## Install
+
+```sh
+npm install @nxtedition/timers
+```
+
+## Usage
+
+```js
+import { setTimeout, clearTimeout } from '@nxtedition/timers'
+
+// Short delays use native setTimeout (full resolution)
+const handle = setTimeout(
+  (data) => {
+    console.log(data)
+  },
+  50,
+  'hello',
+)
+
+// Long delays use pooled timers (500ms resolution, lower overhead)
+const pooled = setTimeout(
+  (data) => {
+    console.log(data)
+  },
+  5000,
+  'world',
+)
+
+// Clear works for both
+clearTimeout(handle)
+clearTimeout(pooled)
+```
+
+### Opaque data
+
+The third argument is passed directly to the callback, avoiding closure allocations:
+
+```js
+setTimeout(
+  (ctx) => {
+    ctx.connection.write(ctx.payload)
+  },
+  5000,
+  { connection, payload },
+)
+```
+
+### Refreshing timers
+
+Pooled timers (delay >= 1000ms) support `.refresh()` to reset the delay without creating a new timer:
+
+```js
+const handle = setTimeout(
+  () => {
+    console.log('idle timeout')
+  },
+  30000,
+  undefined,
+)
+
+// On activity, reset the timer
+handle.refresh()
+```
+
+## API
+
+### `setTimeout(callback, delay, opaque)`
+
+Schedule `callback(opaque)` after `delay` milliseconds.
+
+- `delay < 1000` — delegates to native `globalThis.setTimeout`
+- `delay >= 1000` — uses the pooled timer mechanism (500ms resolution)
+
+Returns a handle that can be passed to `clearTimeout`.
+
+### `clearTimeout(handle)`
+
+Cancel a pending timer. Works with both native and pooled handles. Passing `null` or `undefined` is a no-op.
+
+## How it works
+
+All pooled timers share a single `setTimeout` handle that fires every 500ms. On each tick, pending timers are checked and expired ones are fired. This means pooled timers have at most ~500ms of jitter but dramatically reduce the number of active OS timer handles when many long-lived timers are in use (e.g. connection idle timeouts, retry delays).
+
+The internal interval is `unref()`'d so it does not keep the process alive.
+
+## Benchmark
+
+```sh
+yarn benchmark
+```
+
+Results on Apple M3 Pro / Node.js 25.3.0:
+
+| Benchmark                      | native setTimeout | pooled setTimeout | speedup |
+| ------------------------------ | ----------------: | ----------------: | ------: |
+| create + clear                 |         250.91 ns |          58.90 ns |    4.3x |
+| create + clear (GC)            |           1.95 µs |          73.99 ns |   26.4x |
+| batch create + clear 100x (GC) |          41.84 µs |           9.80 µs |    4.3x |
+
+Pooled timers avoid native OS timer handles, which are expensive C++ objects for the GC to trace. The advantage grows under GC pressure — up to **26x** faster when GC is forced per iteration.
+
+## License
+
+MIT

package/lib/index.bench.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/index.d.ts

@@ -0,0 +1,12 @@
+declare class Timeout {
+    callback: (opaque: unknown) => void;
+    delay: number;
+    opaque: unknown;
+    state: number;
+    constructor(callback: (opaque: unknown) => void, delay: number, opaque: unknown);
+    refresh(): void;
+    clear(): void;
+}
+export declare function setTimeout<T>(callback: (opaque: T) => void, delay: number, opaque: T): Timeout | ReturnType<typeof globalThis.setTimeout>;
+export declare function clearTimeout(timeout: Timeout | ReturnType<typeof globalThis.setTimeout> | null | undefined): void;
+export {};

package/lib/index.js

@@ -0,0 +1,100 @@
+let fastNow = 0
+let fastNowTimeout                                                  = null
+
+const fastTimers            = []
+
+function onTimeout()       {
+  fastNow += 500
+
+  let len = fastTimers.length
+  let idx = 0
+  while (idx < len) {
+    const timer = fastTimers[idx]
+
+    if (timer.state === 0) {
+      timer.state = fastNow + timer.delay
+    } else if (timer.state > 0 && fastNow >= timer.state) {
+      timer.state = -1
+      timer.callback(timer.opaque)
+    }
+
+    if (timer.state === -1) {
+      timer.state = -2
+      if (idx !== len - 1) {
+        fastTimers[idx] = fastTimers.pop() 
+      } else {
+        fastTimers.pop()
+      }
+      len -= 1
+    } else {
+      idx += 1
+    }
+  }
+
+  if (fastTimers.length > 0) {
+    refreshTimeout()
+  }
+}
+
+function refreshTimeout()       {
+  if (fastNowTimeout) {
+    fastNowTimeout.refresh()
+  } else {
+    fastNowTimeout = globalThis.setTimeout(onTimeout, 500)
+    fastNowTimeout.unref()
+  }
+}
+
+class Timeout {
+  callback                           
+  delay        
+  opaque         
+
+  //  -2 not in timer list
+  //  -1 in timer list but inactive
+  //   0 in timer list waiting for time
+  // > 0 in timer list waiting for time to expire
+  state         = -2
+
+  constructor(callback                           , delay        , opaque         ) {
+    this.callback = callback
+    this.delay = delay
+    this.opaque = opaque
+    this.refresh()
+  }
+
+  refresh()       {
+    if (this.state === -2) {
+      fastTimers.push(this)
+      if (!fastNowTimeout || fastTimers.length === 1) {
+        refreshTimeout()
+      }
+    }
+
+    this.state = 0
+  }
+
+  clear()       {
+    this.state = -1
+  }
+}
+
+export function setTimeout   (
+  callback                     ,
+  delay        ,
+  opaque   ,
+)                                                     {
+  return delay < 1e3
+    ? globalThis.setTimeout(callback, delay, opaque)
+    : new Timeout(callback                             , delay, opaque)
+}
+
+export function clearTimeout(
+  timeout                                                                       ,
+)       {
+  if (timeout instanceof Timeout) {
+    timeout.clear()
+  } else if (timeout != null) {
+    globalThis.clearTimeout(timeout)
+  }
+}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@nxtedition/timers",
+  "version": "1.0.0",
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "files": [
+    "lib",
+    "README.md",
+    "LICENSE"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "rimraf lib && tsc && amaroc ./src/index.ts && mv src/index.js lib/",
+    "prepublishOnly": "yarn build",
+    "typecheck": "tsc --noEmit",
+    "test": "node --test",
+    "test:ci": "node --test",
+    "benchmark": "node --experimental-strip-types src/index.bench.ts"
+  },
+  "devDependencies": {
+    "@types/node": "^25.2.3",
+    "amaroc": "^1.0.1",
+    "mitata": "^1.0.34",
+    "oxlint-tsgolint": "^0.12.2",
+    "rimraf": "^6.1.2",
+    "typescript": "^5.9.3"
+  },
+  "gitHead": "12c38fec15bd155797cb1edae372a81061715df3"
+}