@blamejs/core 0.5.16 → 0.5.18

package/lib/mail.js

@@ -63,8 +63,8 @@
  * diagnostic logs identify the provider that rejected the message.
  */
 var C = require("./constants");
+var crypto = require("./crypto");
 var lazyRequire = require("./lazy-require");
-var nodeCrypto = require("node:crypto");
 var audit = lazyRequire(function () { return require("./audit"); });
 var httpClient = lazyRequire(function () { return require("./http-client"); });
 var net = lazyRequire(function () { return require("net"); });
@@ -297,7 +297,7 @@ function _newBoundary(label) {
   // convention. RFC 5322 only requires uniqueness within a message,
   // but consistency with how every other identifier in lib/ is built
   // wins over premature differentiation.
-  return "blamejs-" + label + "-" + Date.now() + "-" + nodeCrypto.randomBytes(8).toString("hex");
+  return "blamejs-" + label + "-" + Date.now() + "-" + crypto.generateToken(8);
 }
 
 // base64-encode the buffer with line wrapping at 76 chars (RFC 2045

package/lib/middleware/api-encrypt.js

@@ -174,7 +174,7 @@ function create(opts) {
   validateOpts(opts, [
     "keypair", "keypairs", "replayWindowMs", "pruneIntervalMs",
     "nonceStore", "exemptPaths", "contentTypes", "audit",
-    "maxDecryptedBytes",
+    "maxDecryptedBytes", "trustProxy",
   ], "middleware.apiEncrypt");
   var keypairs       = _resolveKeypairs(opts);
   var activeKeypair  = keypairs[0];
@@ -205,6 +205,7 @@ function create(opts) {
         ? opts.contentTypes.slice()
         : DEFAULT_CONTENT_TYPES.slice());
   var auditOn        = opts.audit !== false;
+  var trustProxy     = opts.trustProxy === true;
   var lastPruneAt    = 0;
 
   function _isExempt(req) {
@@ -233,7 +234,7 @@ function create(opts) {
   function _emitFailure(req, reason) {
     var info = {
       reason:    reason,
-      ip:        (req.socket && req.socket.remoteAddress) || null,
+      ip:        requestHelpers.clientIp(req, { trustProxy: trustProxy }),
       path:      req.pathname || (req.url || "/").split("?")[0],
       method:    req.method,
       ts:        new Date().toISOString(),

package/lib/middleware/body-parser.js

@@ -113,6 +113,7 @@ var os = require("os");
 var path = require("path");
 var nodeCrypto = require("node:crypto");
 var atomicFile = require("../atomic-file");
+var crypto = require("../crypto");
 var safeJson = require("../safe-json");
 var validateOpts = require("../validate-opts");
 var C = require("../constants");
@@ -708,7 +709,7 @@ async function _parseMultipart(req, opts, ctParams) {
 
               // Generate the tmp path — never derived from the
               // operator-supplied filename.
-              var unique = nodeCrypto.randomBytes(16).toString("hex");
+              var unique = crypto.generateToken(16);
               currentTmpPath = path.join(tmpDir, "blamejs-up-" + unique);
               try {
                 currentFd = fs.openSync(currentTmpPath, "wx", 0o600);

package/lib/middleware/compression.js

@@ -209,9 +209,10 @@ function _appendVary(existing, token) {
   if (!existing) return token;
   var lc = String(existing).toLowerCase();
   if (lc === "*") return "*"; // Vary: * already stops caches; don't dilute.
-  var parts = String(existing).split(",").map(function (p) { return p.trim(); });
+  var parts = requestHelpers.parseListHeader(existing);
+  var lcToken = token.toLowerCase();
   for (var i = 0; i < parts.length; i++) {
-    if (parts[i].toLowerCase() === token.toLowerCase()) return String(existing);
+    if (parts[i].toLowerCase() === lcToken) return String(existing);
   }
   parts.push(token);
   return parts.join(", ");

package/lib/middleware/cors.js

@@ -236,7 +236,7 @@ function create(opts) {
       if (refuseUnknown) {
         var requestedHdrs = req.headers["access-control-request-headers"];
         if (requestedHdrs) {
-          var asked = String(requestedHdrs).toLowerCase().split(",").map(function (s) { return s.trim(); }).filter(Boolean);
+          var asked = requestHelpers.parseListHeader(requestedHdrs, { lowercase: true });
           for (var ah = 0; ah < asked.length; ah++) {
             if (allowedHeadersSet.indexOf(asked[ah]) === -1) {
               if (typeof res.writeHead === "function") {

package/lib/middleware/rate-limit.js

@@ -46,6 +46,7 @@
 var C = require("../constants");
 var lazyRequire = require("../lazy-require");
 var requestHelpers = require("../request-helpers");
+var safeAsync = require("../safe-async");
 var validateOpts = require("../validate-opts");
 var clusterStorage = require("../cluster-storage");
 
@@ -71,13 +72,12 @@ function _memoryBackend(opts) {
   var buckets = new Map();
 
   // Periodic GC of stale buckets so the map doesn't grow unbounded.
-  var gcInterval = setInterval(function () {
+  var gcInterval = safeAsync.repeating(function () {
     var cutoff = Date.now() - C.TIME.hours(1);
     for (var k of buckets.keys()) {
       if (buckets.get(k).lastRefillAt < cutoff) buckets.delete(k);
     }
-  }, C.TIME.minutes(5));
-  if (typeof gcInterval.unref === "function") gcInterval.unref();
+  }, C.TIME.minutes(5), { name: "rate-limit-gc" });
 
   // Memory backend returns verdicts SYNCHRONOUSLY — no awaitable.
   // The middleware checks `.then` to decide whether to chain. Keeping
@@ -118,7 +118,7 @@ function _memoryBackend(opts) {
   }
 
   function close() {
-    try { clearInterval(gcInterval); } catch (_e) {}
+    try { gcInterval.stop(); } catch (_e) {}
     buckets.clear();
   }
 

package/lib/mtls-engine-default.js

@@ -32,6 +32,7 @@ var nodeCrypto = require("node:crypto");
 var pki = require("./vendor/pki.cjs");
 
 var C = require("./constants");
+var crypto = require("./crypto");
 var { FrameworkError } = require("./framework-error");
 
 var x509 = pki.x509;
@@ -108,7 +109,7 @@ async function generateCa(opts) {
   var keys = await webcrypto.subtle.generateKey(CA_KEY_ALG, true, CA_KEY_USAGES);
   var now  = new Date();
   var ca = await x509.X509CertificateGenerator.createSelfSigned({
-    serialNumber: nodeCrypto.randomBytes(16).toString("hex"),
+    serialNumber: crypto.generateToken(16),
     name: "CN=" + caName + ",OU=CAv" + generation,
     notBefore: now,
     notAfter: new Date(now.getTime() + C.TIME.days(CA_VALIDITY_DAYS)),
@@ -143,7 +144,7 @@ async function signClientCert(opts) {
   var now      = new Date();
   var notAfter = new Date(now.getTime() + C.TIME.days(validityDays));
   var clientCert = await x509.X509CertificateGenerator.create({
-    serialNumber: nodeCrypto.randomBytes(16).toString("hex"),
+    serialNumber: crypto.generateToken(16),
     subject: "CN=" + cn,
     issuer: caCert.subject,
     notBefore: now,

package/lib/nonce-store.js

@@ -43,6 +43,7 @@
 
 var clusterStorage = require("./cluster-storage");
 var C = require("./constants");
+var safeAsync = require("./safe-async");
 var { defineClass } = require("./framework-error");
 
 var NonceStoreError = defineClass("NonceStoreError");
@@ -59,13 +60,12 @@ function _memoryBackend(opts) {
   var sweepIntervalMs = opts.sweepIntervalMs || DEFAULT_SWEEP_INTERVAL_MS;
   var seen = new Map();   // nonce -> expireAt
 
-  var sweepTimer = setInterval(function () {
+  var sweepTimer = safeAsync.repeating(function () {
     var now = Date.now();
     for (var entry of seen) {
       if (entry[1] <= now) seen.delete(entry[0]);
     }
-  }, sweepIntervalMs);
-  if (typeof sweepTimer.unref === "function") sweepTimer.unref();
+  }, sweepIntervalMs, { name: "nonce-sweep" });
 
   function checkAndInsert(nonce, expireAt) {
     if (typeof nonce !== "string" || nonce.length === 0) {
@@ -92,7 +92,7 @@ function _memoryBackend(opts) {
   }
 
   function close() {
-    if (sweepTimer) { clearInterval(sweepTimer); sweepTimer = null; }
+    if (sweepTimer) { sweepTimer.stop(); sweepTimer = null; }
     seen.clear();
   }
 

package/lib/notify.js

@@ -48,6 +48,7 @@
  */
 
 var lazyRequire = require("./lazy-require");
+var bootLog = require("./log");
 var requestHelpers = require("./request-helpers");
 var safeAsync = require("./safe-async");
 var safeUrl = require("./safe-url");
@@ -274,7 +275,6 @@ function logTransport(opts) {
   if (opts.logger && typeof opts.logger.info === "function") {
     logger = opts.logger;
   } else {
-    var bootLog = require("./log");
     logger = bootLog.boot("notify.log");
     // boot returns a fn-with-fields shape; tolerate both.
     if (typeof logger === "function") {

package/lib/otel-export.js

@@ -40,6 +40,7 @@
  * hand-rolled wire format with no compelling benefit at this scope.
  */
 var C = require("./constants");
+var safeAsync = require("./safe-async");
 var validateOpts = require("./validate-opts");
 var { defineClass } = require("./framework-error");
 
@@ -117,7 +118,7 @@ function create(opts) {
   var counters = new Map();          // bucketKey → { name, attrs, value, startUnixNano }
   var observations = new Map();      // bucketKey → { name, attrs, sum, count, min, max, startUnixNano }
   var startUnixNano = String(Date.now() * 1e6);
-  var timer = null;
+  var loop = null;
   var closed = false;
 
   function recordCounter(name, value, attrs) {
@@ -235,20 +236,14 @@ function create(opts) {
     }
   }
 
-  function _scheduleFlush() {
-    if (intervalMs === 0 || closed) return;
-    timer = setTimeout(function () {
-      flush().catch(function (_e) { /* never let a flush error crash the timer */ });
-      _scheduleFlush();
-    }, intervalMs);
-    if (typeof timer.unref === "function") timer.unref();
+  if (intervalMs > 0) {
+    loop = safeAsync.flushLoop(flush, intervalMs, { name: "otel-flush" });
   }
-  _scheduleFlush();
 
   function close() {
     if (closed) return;
     closed = true;
-    if (timer) { clearTimeout(timer); timer = null; }
+    if (loop) { loop.stop(); loop = null; }
     return flush().catch(function (_e) { /* close path swallows final-flush errors */ });
   }
 

package/lib/pagination.js

@@ -89,6 +89,7 @@
  */
 
 var nodeCrypto = require("node:crypto");
+var crypto = require("./crypto");
 var { defineClass } = require("./framework-error");
 
 var PaginationError = defineClass("PaginationError", { alwaysPermanent: true });
@@ -171,7 +172,7 @@ function decodeCursor(token, secret) {
     throw new PaginationError("pagination/bad-cursor", "cursor base64 decode failed");
   }
   var expected = _tag(sb, json);
-  if (tag.length !== expected.length || !nodeCrypto.timingSafeEqual(tag, expected)) {
+  if (!crypto.timingSafeEqual(tag, expected)) {
     throw new PaginationError("pagination/cursor-tag-mismatch",
       "cursor HMAC verification failed (tampered or wrong secret)");
   }

package/lib/parsers/index.js

@@ -7,9 +7,6 @@
  *   xml  — RFC-compliant subset; XXE / DOCTYPE / billion-laughs blocked
  *           by default; depth + element + attribute count limits;
  *           numeric-character-ref bounds checked
- *   csv  — RFC 4180 parsing + writer with formula-injection prevention
- *           (cells starting with =/+/-/@/tab/CR get a single-quote
- *           prefix on stringify so Excel doesn't execute them)
  *   toml — TOML 1.0 parsing with depth + size limits;
  *           prototype-pollution rejection on dotted-key path segments;
  *           strict same-key redefinition (silent overwrite would mask
@@ -49,15 +46,14 @@
  *
  * Public API:
  *   parsers.xml.parse(input, opts?)              → object
- *   parsers.csv.parse(input, opts?)              → array
- *   parsers.csv.stringify(rows, opts?)           → string
+ *
+ * (CSV moved to top-level `b.csv` in v0.5.17 — same surface unified.)
  *
  * Error types: each parser exports its own *SafeError class with .code
- * matching the format (xml/..., csv/...).
+ * matching the format (xml/..., toml/...).
  */
 module.exports = {
   xml:  require("./safe-xml"),
-  csv:  require("./safe-csv"),
   toml: require("./safe-toml"),
   yaml: require("./safe-yaml"),
   env:  require("./safe-env"),

package/lib/parsers/safe-env.js

@@ -57,6 +57,7 @@
 var C = require("../constants");
 var atomicFile = require("../atomic-file");
 var safeBuffer = require("../safe-buffer");
+var safeJson = require("../safe-json");
 var { FrameworkError } = require("../framework-error");
 var { boot } = require("../log");
 
@@ -275,7 +276,6 @@ function _coerceType(rawValue, type, key) {
     );
   }
   if (type === "json") {
-    var safeJson = require("./../safe-json");
     try { return safeJson.parse(rawValue); }
     catch (e) {
       throw new SafeEnvError("invalid JSON for key '" + key + "': " + e.message,
@@ -437,7 +437,6 @@ function load(filepath, opts) {
   if (snapshotPath && atomicFile.exists(snapshotPath)) {
     try {
       var snapBuf = atomicFile.readSync(snapshotPath);
-      var safeJson = require("./../safe-json");
       prevValues = safeJson.parse(snapBuf) || {};
     } catch (_e) { /* missing/corrupt snapshot → treat as empty */ }
   }

package/lib/queue-local.js

@@ -31,6 +31,7 @@
  */
 var cluster = require("./cluster");
 var clusterStorage = require("./cluster-storage");
+var C = require("./constants");
 var { generateToken } = require("./crypto");
 var cryptoField = require("./crypto-field");
 var lazyRequire = require("./lazy-require");
@@ -108,7 +109,7 @@ function create(_config) {
     cluster.requireLeader();
     opts = opts || {};
     var nowMs = Date.now();
-    var availableAt = nowMs + (opts.delaySeconds ? opts.delaySeconds * 1000 : 0);
+    var availableAt = nowMs + (opts.delaySeconds ? C.TIME.seconds(opts.delaySeconds) : 0);
 
     var priority = (typeof opts.priority === "number" && isFinite(opts.priority))
       ? Math.floor(opts.priority) : 0;

package/lib/queue.js

@@ -31,8 +31,9 @@
  *                                       failed (status='failed')
  */
 var C = require("./constants");
+var clusterStorage = require("./cluster-storage");
+var crypto = require("./crypto");
 var lazyRequire = require("./lazy-require");
-var nodeCrypto = require("node:crypto");
 var observability = require("./observability");
 var protocolDispatcher = require("./protocol-dispatcher");
 var localProto = require("./queue-local");
@@ -125,14 +126,13 @@ function init(opts) {
 
   // Sweep expired leases periodically (every 30s) so crashed-handler jobs
   // get re-pended.
-  sweepTimer = setInterval(function () {
+  sweepTimer = safeAsync.repeating(function () {
     Object.keys(backends).forEach(function (n) {
       if (backends[n].sweepExpired) {
         backends[n].sweepExpired().catch(function () { /* best effort */ });
       }
     });
-  }, 30000);
-  sweepTimer.unref();
+  }, C.TIME.seconds(30), { name: "queue-sweep" });
 
   initialized = true;
 }
@@ -197,7 +197,7 @@ function consume(queueName, handler, opts) {
     }
     rateLimit = {
       max:        opts.rateLimit.max,
-      windowMs:   opts.rateLimit.perSeconds * 1000,
+      windowMs:   C.TIME.seconds(opts.rateLimit.perSeconds),
       timestamps: [],
     };
   }
@@ -466,7 +466,7 @@ async function shutdown(opts) {
     await safeAsync.sleep(50);
   }
   consumers = [];
-  if (sweepTimer) { clearInterval(sweepTimer); sweepTimer = null; }
+  if (sweepTimer) { sweepTimer.stop(); sweepTimer = null; }
 }
 
 function listBackends() {
@@ -485,7 +485,7 @@ function _requireInit() {
 }
 
 function _resetForTest() {
-  if (sweepTimer) { clearInterval(sweepTimer); sweepTimer = null; }
+  if (sweepTimer) { sweepTimer.stop(); sweepTimer = null; }
   consumers.forEach(function (c) { c.cancel(); });
   consumers = [];
   backends = {};
@@ -571,7 +571,7 @@ function enqueueFlow(spec) {
     return Promise.reject(e);
   }
 
-  var flowId = "flow-" + nodeCrypto.randomBytes(8).toString("hex");
+  var flowId = "flow-" + crypto.generateToken(8);
 
   return observability.tap("queue.enqueueFlow",
     { queueName: spec.queueName, flowId: flowId, childCount: spec.children.length },
@@ -603,7 +603,6 @@ function enqueueFlow(spec) {
       }
       // Second pass: write dependsOn (translated to jobIds) for children
       // that need it, and parking-lot their availableAt to MAX_SAFE_INTEGER.
-      var clusterStorage = require("./cluster-storage");
       for (var q = 0; q < jobs.length; q++) {
         var j = jobs[q];
         if (j.dependsOn.length === 0) continue;

package/lib/request-helpers.js

@@ -136,7 +136,7 @@ function clientIp(req, opts) {
   if (trust && req.headers) {
     var xff = req.headers["x-forwarded-for"];
     if (xff) {
-      var hops = String(xff).split(",").map(function (s) { return s.trim(); });
+      var hops = parseListHeader(xff);
       if (trust === true) return hops[0];
       if (typeof trust === "number" && trust >= 1 && hops.length >= trust) {
         return hops[hops.length - trust];
@@ -154,7 +154,8 @@ function requestProtocol(req, opts) {
   if (trust && req.headers) {
     var fwd = req.headers["x-forwarded-proto"];
     if (typeof fwd === "string" && fwd.length > 0) {
-      return String(fwd).split(",")[0].trim().toLowerCase();
+      var hops = parseListHeader(fwd, { lowercase: true });
+      if (hops.length > 0) return hops[0];
     }
   }
   if (req.socket && req.socket.encrypted) return "https";
@@ -162,6 +163,36 @@ function requestProtocol(req, opts) {
   return "http";
 }
 
+// parseListHeader — split a comma-separated header / opt value into a
+// list of trimmed non-empty tokens. Replaces the
+// `String(x).split(",").map(s => s.trim()).filter(Boolean)` chain that
+// was duplicated across cors / compression / scheduler / webhook /
+// websocket / db-schema / cli before v0.5.17.
+//
+//   parseListHeader("a, b , ,c")           → ["a", "b", "c"]
+//   parseListHeader("Foo, Bar", { lowercase: true })
+//                                          → ["foo", "bar"]
+//   parseListHeader(undefined)             → []
+//   parseListHeader("")                    → []
+//
+// Tier-C: tolerant of non-string input (returns []) — these are read
+// from request headers that the network might omit. Callers needing
+// stricter checks layer their own validation on the result.
+function parseListHeader(value, opts) {
+  if (value == null) return [];
+  opts = opts || {};
+  var s = typeof value === "string" ? value : String(value);
+  if (s.length === 0) return [];
+  var parts = s.split(",");
+  var out = [];
+  for (var i = 0; i < parts.length; i++) {
+    var t = parts[i].trim();
+    if (t.length === 0) continue;
+    out.push(opts.lowercase ? t.toLowerCase() : t);
+  }
+  return out;
+}
+
 // Append a token to a `Vary` response header without dropping prior
 // values (compression middleware sets `Vary: Accept-Encoding`, an
 // auth helper might set `Vary: Authorization`, etc.). Idempotent —
@@ -170,7 +201,7 @@ function appendVary(res, value) {
   if (!res || typeof res.getHeader !== "function" || typeof res.setHeader !== "function") return;
   var existing = res.getHeader("Vary");
   if (existing == null || existing === "") { res.setHeader("Vary", value); return; }
-  var tokens = String(existing).split(",").map(function (s) { return s.trim(); }).filter(Boolean);
+  var tokens = parseListHeader(existing);
   var lower = value.toLowerCase();
   for (var i = 0; i < tokens.length; i++) if (tokens[i].toLowerCase() === lower) return;
   tokens.push(value);
@@ -266,6 +297,7 @@ module.exports = {
   extractActorContext:       extractActorContext,
   resolveActorWithOverride:  resolveActorWithOverride,
   parseQualityList:          parseQualityList,
+  parseListHeader:           parseListHeader,
   // v0.5.3 — proxy-trust primitives (default refuses forwarded headers)
   clientIp:                  clientIp,
   requestProtocol:           requestProtocol,

package/lib/restore.js

@@ -52,9 +52,9 @@
  */
 
 var fs = require("fs");
-var nodeCrypto = require("node:crypto");
 var os = require("os");
 var path = require("path");
+var crypto = require("./crypto");
 var restoreBundle = require("./restore-bundle");
 var restoreRollback = require("./restore-rollback");
 var lazyRequire = require("./lazy-require");
@@ -128,7 +128,7 @@ function create(opts) {
         "inspect: bundle '" + bundleId + "' not in storage");
     }
     var pullDir = path.join(os.tmpdir(),
-      "blamejs-restore-inspect-" + nodeCrypto.randomBytes(4).toString("hex"));
+      "blamejs-restore-inspect-" + crypto.generateToken(4));
     try {
       await storage.readBundle(bundleId, pullDir);
       return restoreBundle.inspect({ bundleDir: pullDir });
@@ -150,7 +150,7 @@ function create(opts) {
         "run: bundle '" + bundleId + "' not in storage");
     }
 
-    var pullId = nodeCrypto.randomBytes(4).toString("hex");
+    var pullId = crypto.generateToken(4);
     var pullDir    = path.join(os.tmpdir(), "blamejs-restore-pull-"    + pullId);
     var stagingDir = path.join(os.tmpdir(), "blamejs-restore-staging-" + pullId);
 

package/lib/router.js

@@ -26,6 +26,7 @@ var path = require("path");
 var { URL } = require("url");
 var C = require("./constants");
 var safeAsync = require("./safe-async");
+var safeEnv = require("./parsers/safe-env");
 var websocket = require("./websocket");
 var { boot } = require("./log");
 
@@ -112,7 +113,7 @@ function _makeResponseValidator(spec) {
   //   - BLAMEJS_VALIDATE_RESPONSES=warn (or per-route validateResponse: "warn")
   //     → log a warning; ship the response as-is (prod-safe).
   var perRoute = spec.validateResponse;
-  var globalMode = process.env.BLAMEJS_VALIDATE_RESPONSES;
+  var globalMode = safeEnv.readVar("BLAMEJS_VALIDATE_RESPONSES");
   var mode = (perRoute === "throw" || perRoute === "warn") ? perRoute :
              (globalMode === "throw" || globalMode === "warn") ? globalMode : null;
   if (!mode) return function passthrough(_req, _res, next) { next(); };
@@ -260,9 +261,10 @@ class Router {
       // route dispatch) but before any route-specific handler.
       handlers = [_makeSchemaValidator(split.spec)].concat(handlers);
       // Response validation (dev/opt-in via env or per-route opt).
+      var globalValidateMode = safeEnv.readVar("BLAMEJS_VALIDATE_RESPONSES");
       if (split.spec.response &&
-          (process.env.BLAMEJS_VALIDATE_RESPONSES === "throw" ||
-           process.env.BLAMEJS_VALIDATE_RESPONSES === "warn" ||
+          (globalValidateMode === "throw" ||
+           globalValidateMode === "warn" ||
            split.spec.validateResponse)) {
         handlers = [_makeResponseValidator(split.spec)].concat(handlers);
       }

package/lib/safe-async.js

@@ -494,6 +494,126 @@ class Once {
   hasInvoked() { return this._promise !== null; }
 }
 
+// ---- repeating ----
+//
+// Bounded-cadence interval timer with consistent unref + cancel semantics.
+// Replaces the scattered setInterval ceremony where each caller hand-rolled
+// `var t = setInterval(...); t.unref();` and a corresponding clearInterval
+// in shutdown — easy to forget the unref and silently block process exit.
+//
+//   var sweep = b.safeAsync.repeating(function () {
+//     return cleanup();
+//   }, b.constants.TIME.seconds(30), { name: "cache-sweep" });
+//   ...
+//   sweep.stop();
+//
+// fn may be sync or async. If fn returns a Promise, the next tick fires
+// `intervalMs` after the prior fn() *started* (matching setInterval's
+// fixed-rate semantics, not after-completion). Promise rejections are
+// captured by the optional onError callback; if none provided, they're
+// silently dropped — a repeating timer is by definition fire-and-forget,
+// and an unhandled rejection here would crash the process.
+//
+// opts.unref defaults true: most repeating timers are background sweepers
+// that should NOT keep the process alive. Cluster heartbeat etc. set
+// `unref: false` so the lease keeps the leader from exiting silently.
+
+function repeating(fn, intervalMs, opts) {
+  if (typeof fn !== "function") {
+    throw new SafeAsyncError("repeating: fn must be a function", "async/bad-arg");
+  }
+  if (typeof intervalMs !== "number" || !Number.isFinite(intervalMs) || intervalMs <= 0) {
+    throw new SafeAsyncError("repeating: intervalMs must be a positive finite number, got " + intervalMs,
+      "async/bad-arg");
+  }
+  opts = opts || {};
+  var unref = opts.unref !== false;     // default true
+  var onError = typeof opts.onError === "function" ? opts.onError : null;
+
+  var stopped = false;
+  var timer = setInterval(function () {
+    if (stopped) return;
+    var result;
+    try { result = fn(); }
+    catch (e) { if (onError) { try { onError(e); } catch (_e) { /* swallow */ } } return; }
+    if (result && typeof result.then === "function") {
+      result.then(null, function (e) {
+        if (onError) { try { onError(e); } catch (_e) { /* swallow */ } }
+      });
+    }
+  }, intervalMs);
+  if (unref && typeof timer.unref === "function") timer.unref();
+
+  return {
+    stop: function () {
+      if (stopped) return;
+      stopped = true;
+      clearInterval(timer);
+    },
+  };
+}
+
+// ---- flushLoop ----
+//
+// Schedule fn(), wait for it to settle (resolve or reject), then schedule
+// the next fn() `intervalMs` later. Differs from `repeating` (fixed-rate,
+// fire-and-forget) — flushLoop is the after-completion pattern most
+// background flushers want: never overlap two flushes, and don't accumulate
+// backlog if a flush is slow.
+//
+//   var loop = b.safeAsync.flushLoop(function () {
+//     return otelExporter.flush();
+//   }, b.constants.TIME.seconds(15), { name: "otel-flush" });
+//   ...
+//   loop.stop();
+//
+// Always unref'd — a pending flush should never keep the process alive
+// (the operator's b.appShutdown drives the final drain explicitly).
+// onError catches rejections; without one, they're silently dropped.
+
+function flushLoop(fn, intervalMs, opts) {
+  if (typeof fn !== "function") {
+    throw new SafeAsyncError("flushLoop: fn must be a function", "async/bad-arg");
+  }
+  if (typeof intervalMs !== "number" || !Number.isFinite(intervalMs) || intervalMs <= 0) {
+    throw new SafeAsyncError("flushLoop: intervalMs must be a positive finite number, got " + intervalMs,
+      "async/bad-arg");
+  }
+  opts = opts || {};
+  var onError = typeof opts.onError === "function" ? opts.onError : null;
+
+  var stopped = false;
+  var timer = null;
+
+  function _schedule() {
+    if (stopped) return;
+    timer = setTimeout(function () {
+      timer = null;
+      if (stopped) return;
+      var settled;
+      try { settled = Promise.resolve(fn()); }
+      catch (e) {
+        if (onError) { try { onError(e); } catch (_e) { /* swallow */ } }
+        _schedule();
+        return;
+      }
+      settled.then(null, function (e) {
+        if (onError) { try { onError(e); } catch (_e) { /* swallow */ } }
+      }).then(_schedule);
+    }, intervalMs);
+    if (typeof timer.unref === "function") timer.unref();
+  }
+  _schedule();
+
+  return {
+    stop: function () {
+      if (stopped) return;
+      stopped = true;
+      if (timer) { clearTimeout(timer); timer = null; }
+    },
+  };
+}
+
 // ---- Re-exports of resilience primitives from lib/retry.js ----
 //
 // withRetry + CircuitBreaker live in lib/retry.js (the canonical home).
@@ -510,6 +630,8 @@ module.exports = {
   withSignal:         withSignal,
   withTimeoutSignal:  withTimeoutSignal,
   sleep:              sleep,
+  repeating:          repeating,
+  flushLoop:          flushLoop,
   safeAwait:          safeAwait,
   Mutex:              Mutex,
   Semaphore:          Semaphore,