@naturalcycles/backend-lib 9.64.0 → 9.65.0

package/dist/server/eventLoop.util.d.ts

@@ -5,6 +5,11 @@ import type { Integer, NonNegativeInteger, NumberOfMilliseconds, NumberOfPercent
  * Also, monitors GC performance.
  * Once per `measureInterval` sends a callback with stats.
  *
+ * On Node >=24.19 (or >=26.5) delays are sampled once per event loop iteration
+ * (`samplePerIteration`), so stats reflect true per-iteration delay:
+ * expect p50/mean near 0 on a healthy service, instead of the ~`resolution` baseline
+ * reported by older interval-based sampling.
+ *
  * @experimental
  */
 export declare class EventLoopMonitor {
@@ -22,10 +27,6 @@ export declare class EventLoopMonitor {
     stop(): void;
 }
 export interface EventLoopMonitorCfg {
-    /**
-     * Defaults to 20.
-     */
-    resolution?: NumberOfMilliseconds;
     /**
      * Defaults to 60_000 ms
      */

package/dist/server/eventLoop.util.js

@@ -21,12 +21,24 @@ import { monitorEventLoopDelay, performance, PerformanceObserver } from 'node:pe
  * Also, monitors GC performance.
  * Once per `measureInterval` sends a callback with stats.
  *
+ * On Node >=24.19 (or >=26.5) delays are sampled once per event loop iteration
+ * (`samplePerIteration`), so stats reflect true per-iteration delay:
+ * expect p50/mean near 0 on a healthy service, instead of the ~`resolution` baseline
+ * reported by older interval-based sampling.
+ *
  * @experimental
  */
 export class EventLoopMonitor {
     constructor(cfg = {}) {
-        const { resolution = 20, measureInterval = 60_000 } = cfg;
-        this.eld = monitorEventLoopDelay({ resolution });
+        const { measureInterval = 60_000 } = cfg;
+        const eldOptions = {
+            // Node >=24.19 / >=26.5: sample once per event loop iteration (uv_prepare/uv_check hooks),
+            // which measures actual per-iteration delay instead of timer jitter.
+            // More accurate (no `resolution` offset baked into every percentile) and cheaper.
+            // Older Node silently ignores this option and falls back to interval-based sampling.
+            samplePerIteration: true,
+        };
+        this.eld = monitorEventLoopDelay(eldOptions);
         this.eld.enable();
         this.lastElu = performance.eventLoopUtilization();
         this.po = new PerformanceObserver(list => {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@naturalcycles/backend-lib",
   "type": "module",
-  "version": "9.64.0",
+  "version": "9.65.0",
   "dependencies": {
     "@naturalcycles/db-lib": "^10",
     "@naturalcycles/js-lib": "^15",
@@ -45,7 +45,7 @@
   "devDependencies": {
     "@sentry/node-core": "^10",
     "@types/busboy": "^1",
-    "typescript": "rc",
+    "typescript": "^7",
     "fastify": "^5",
     "@naturalcycles/dev-lib": "0.0.0"
   },

package/src/server/eventLoop.util.ts

@@ -1,4 +1,8 @@
-import type { EventLoopUtilization, IntervalHistogram } from 'node:perf_hooks'
+import type {
+  EventLoopMonitorOptions,
+  EventLoopUtilization,
+  IntervalHistogram,
+} from 'node:perf_hooks'
 import { monitorEventLoopDelay, performance, PerformanceObserver } from 'node:perf_hooks'
 import type {
   Integer,
@@ -30,13 +34,25 @@ import type {
  * Also, monitors GC performance.
  * Once per `measureInterval` sends a callback with stats.
  *
+ * On Node >=24.19 (or >=26.5) delays are sampled once per event loop iteration
+ * (`samplePerIteration`), so stats reflect true per-iteration delay:
+ * expect p50/mean near 0 on a healthy service, instead of the ~`resolution` baseline
+ * reported by older interval-based sampling.
+ *
  * @experimental
  */
 export class EventLoopMonitor {
   constructor(cfg: EventLoopMonitorCfg = {}) {
-    const { resolution = 20, measureInterval = 60_000 } = cfg
-
-    this.eld = monitorEventLoopDelay({ resolution })
+    const { measureInterval = 60_000 } = cfg
+
+    const eldOptions: EventLoopMonitorOptions2 = {
+      // Node >=24.19 / >=26.5: sample once per event loop iteration (uv_prepare/uv_check hooks),
+      // which measures actual per-iteration delay instead of timer jitter.
+      // More accurate (no `resolution` offset baked into every percentile) and cheaper.
+      // Older Node silently ignores this option and falls back to interval-based sampling.
+      samplePerIteration: true,
+    }
+    this.eld = monitorEventLoopDelay(eldOptions)
     this.eld.enable()
 
     this.lastElu = performance.eventLoopUtilization()
@@ -107,11 +123,6 @@ export class EventLoopMonitor {
 }
 
 export interface EventLoopMonitorCfg {
-  /**
-   * Defaults to 20.
-   */
-  resolution?: NumberOfMilliseconds
-
   /**
    * Defaults to 60_000 ms
    */
@@ -156,3 +167,11 @@ export interface EventLoopStats {
    */
   gcCPU: Integer
 }
+
+/**
+ * Extends the Node types with `samplePerIteration` (added in Node 24.19 / 26.5).
+ * Remove once @types/node declares it.
+ */
+interface EventLoopMonitorOptions2 extends EventLoopMonitorOptions {
+  samplePerIteration?: boolean
+}