@blamejs/core 0.5.16 → 0.5.18

package/CHANGELOG.md

@@ -8,6 +8,8 @@ upgrading across more than a few patches at a time.
 
 ## v0.5.x
 
+- **0.5.17** (2026-05-01) — primitive-drift sweep: csv unify + 3 new shared primitives
+- **0.5.16** (2026-04-30) — b.otelExport: OTLP/HTTP exporter for b.observability
 - **0.5.15** (2026-04-30) — b.archive: ZIP creation
 - **0.5.14** (2026-04-30) — b.time: timezone-aware datetime arithmetic + formatting
 - **0.5.13** (2026-04-30) — b.testing.request: supertest-style chainable HTTP test helper

package/lib/backup/index.js

@@ -60,9 +60,9 @@
  */
 
 var fs = require("fs");
-var nodeCrypto = require("node:crypto");
 var os = require("os");
 var path = require("path");
+var crypto = require("../crypto");
 var atomicFile = require("../atomic-file");
 var backupBundle = require("./bundle");
 var lazyRequire = require("../lazy-require");
@@ -80,7 +80,7 @@ function _isValidBundleId(s) {
 }
 
 function _generateBundleId() {
-  return atomicFile.pathTimestamp() + "-" + nodeCrypto.randomBytes(4).toString("hex");
+  return atomicFile.pathTimestamp() + "-" + crypto.generateToken(4);
 }
 
 function _dirSize(p) {
@@ -243,6 +243,11 @@ function create(opts) {
   // running backup against an external db handle still work).
   if (flushBeforeBackup === null && opts.flushBeforeBackup !== false) {
     try {
+      // Inline require: backup is a leaf module the framework re-exports
+      // without forcing operators to also bring in lib/db. Hoisting to
+      // top-of-file would require everyone using `b.backup` from
+      // outside the framework to have ./db loadable in the same module
+      // graph, which CLI tools and stand-alone backup runners don't.
       var dbModule = require("../db");
       if (typeof dbModule.flushToDisk === "function") {
         flushBeforeBackup = function () { dbModule.flushToDisk(); };

package/lib/cache.js

@@ -94,6 +94,7 @@ var clusterStorage = require("./cluster-storage");
 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 { CacheError } = require("./framework-error");
 
@@ -434,12 +435,11 @@ function _memoryBackend(cfg) {
 
   function _startSweep(intervalMs) {
     if (sweepTimer) return;
-    sweepTimer = setInterval(_sweep, intervalMs);
-    if (typeof sweepTimer.unref === "function") sweepTimer.unref();
+    sweepTimer = safeAsync.repeating(_sweep, intervalMs, { name: "cache-sweep" });
   }
 
   async function close() {
-    if (sweepTimer) { clearInterval(sweepTimer); sweepTimer = null; }
+    if (sweepTimer) { sweepTimer.stop(); sweepTimer = null; }
     entries.clear();
     tagIndex.clear();
     totalBytes = 0;
@@ -579,15 +579,11 @@ function _clusterBackend(cfg) {
   }
 
   function _startSweep(intervalMs) {
-    var t = setInterval(function () {
-      _sweep().catch(function () { /* sweeper best-effort; next pass picks it up */ });
-    }, intervalMs);
-    if (typeof t.unref === "function") t.unref();
-    cfg._sweepTimer = t;
+    cfg._sweepTimer = safeAsync.repeating(_sweep, intervalMs, { name: "cache-sweep-cluster" });
   }
 
   async function close() {
-    if (cfg._sweepTimer) { clearInterval(cfg._sweepTimer); cfg._sweepTimer = null; }
+    if (cfg._sweepTimer) { cfg._sweepTimer.stop(); cfg._sweepTimer = null; }
   }
 
   return {

package/lib/cli.js

@@ -35,15 +35,16 @@
  */
 
 var fs = require("node:fs");
-var nodeCrypto = require("node:crypto");
 var os = require("node:os");
 var path = require("path");
 var apiSnapshot = require("./api-snapshot");
 var auditTools = require("./audit-tools");
 var cliHelpers = require("./cli-helpers");
 var constants = require("./constants");
+var crypto = require("./crypto");
 var dev = require("./dev");
 var migrations = require("./migrations");
+var requestHelpers = require("./request-helpers");
 var restoreBundle = require("./restore-bundle");
 var seeders = require("./seeders");
 var vaultPassphraseOps = require("./vault/passphrase-ops");
@@ -746,7 +747,7 @@ async function _runApiKey(args, ctx) {
       var scopes  = args.flags.scopes;
       if (!ownerId || ownerId === true) return report.error("--owner-id <id> is required", 2);
       if (!scopes  || scopes === true)  return report.error("--scopes <comma-separated> is required", 2);
-      var scopeList = String(scopes).split(",").map(function (s) { return s.trim(); }).filter(Boolean);
+      var scopeList = requestHelpers.parseListHeader(scopes);
       if (scopeList.length === 0) {
         return report.error("--scopes must contain at least one non-empty scope", 2);
       }
@@ -902,7 +903,7 @@ async function _runBackup(args, ctx) {
 
   if (sub === "verify") {
     var stagingDir = path.join(os.tmpdir(),
-      "blamejs-backup-verify-" + nodeCrypto.randomBytes(8).toString("hex"));
+      "blamejs-backup-verify-" + crypto.generateToken(8));
     try {
       var r = await restoreBundle.extract({
         bundleDir:  bundleDir,

package/lib/cluster.js

@@ -51,10 +51,21 @@
  *   await cluster.shutdown()             releases lease, stops heartbeat
  */
 var C = require("./constants");
+var clusterProviderDb = require("./cluster-provider-db");
+var crypto = require("./crypto");
+var lazyRequire = require("./lazy-require");
 var { boot } = require("./log");
+var safeAsync = require("./safe-async");
+var safeJson = require("./safe-json");
 var safeUrl = require("./safe-url");
 var { FrameworkError, ClusterError } = require("./framework-error");
 
+// Lazy: vault → db → cluster forms a load-time chain, and external-db is
+// loaded before its init has run; both are safe to call once cluster
+// reaches runtime, but eager require here would deadlock the load order.
+var externalDb = lazyRequire(function () { return require("./external-db"); });
+var vault = lazyRequire(function () { return require("./vault"); });
+
 var DEFAULT_LEASE_TTL    = C.TIME.seconds(30);
 var DEFAULT_HEARTBEAT    = C.TIME.seconds(10);
 var MIN_LEASE_TTL        = C.TIME.seconds(5);
@@ -184,8 +195,7 @@ async function init(opts) {
       throw _err("INVALID_CONFIG",
         "cluster.init requires either { provider } or { externalDbBackend }", true);
     }
-    var dbProvider = require("./cluster-provider-db");
-    provider = dbProvider.create({
+    provider = clusterProviderDb.create({
       externalDbBackend: opts.externalDbBackend,
       dialect:           opts.dialect,
     });
@@ -227,8 +237,7 @@ async function init(opts) {
   }
 
   // Start heartbeat
-  heartbeatTimer = setInterval(_heartbeat, heartbeatMs);
-  heartbeatTimer.unref();
+  heartbeatTimer = safeAsync.repeating(_heartbeat, heartbeatMs, { name: "cluster-heartbeat" });
 }
 
 // Cluster-mode equivalent of db.js's single-node audit.tip-sidecar
@@ -264,15 +273,9 @@ async function init(opts) {
 //     hash → FATAL via process.exit(1). Same posture as the
 //     single-node audit.tip sidecar rollback check.
 async function _checkChainTipRollback(chainName, logTable, tipTable) {
-  // Lazy require because external-db isn't available before
-  // cluster.init (and cluster is required from many subsystems —
-  // a top-of-file require would form a circular load with
-  // external-db's audit emit path).
-  var externalDb = require("./external-db");
-
   var tipRows;
   try {
-    tipRows = await externalDb.query(
+    tipRows = await externalDb().query(
       "SELECT atMonotonicCounter, rowHash FROM " + tipTable +
       " WHERE scope = '" + chainName + "'",
       [],
@@ -294,7 +297,7 @@ async function _checkChainTipRollback(chainName, logTable, tipTable) {
   var tipCounter = Number(tip.atMonotonicCounter);
   var tipHash = tip.rowHash;
 
-  var currentRows = await externalDb.query(
+  var currentRows = await externalDb().query(
     "SELECT MAX(monotonicCounter) AS m FROM " + logTable,
     [],
     { backend: configuredExternalDbBackend }
@@ -313,7 +316,7 @@ async function _checkChainTipRollback(chainName, logTable, tipTable) {
   }
 
   if (tipHash) {
-    var hashRows = await externalDb.query(
+    var hashRows = await externalDb().query(
       "SELECT rowHash FROM " + logTable + " WHERE monotonicCounter = " +
       (configuredDialect === "postgres" ? "$1" : "?"),
       [tipCounter],
@@ -347,14 +350,9 @@ async function _checkChainTipRollback(chainName, logTable, tipTable) {
 // posture as the audit-tip rollback check skipping when there's no
 // audit-tip table.
 function _vaultKeyFingerprint() {
-  // Lazy require to avoid the circular load risk: vault → db → cluster
-  // (the audit module pulls cluster in, db loads audit at init).
-  var vault = require("./vault");
-  var crypto = require("./crypto");
-  var safeJson = require("./safe-json");
   var keysJson;
   try {
-    keysJson = vault.getKeysJson();
+    keysJson = vault().getKeysJson();
   } catch (e) {
     // vault.init() not called — gates-only mode. Skip silently.
     if (/vault.init\(\) must be awaited/.test((e && e.message) || "")) {
@@ -380,7 +378,6 @@ async function _checkVaultKeyConsistency() {
     log("vault not initialized — skipping vault-key consistency check (cluster gates-only mode)");
     return;
   }
-  var externalDb = require("./external-db");
   var nowMs = Date.now();
   var ph = configuredDialect === "postgres";
 
@@ -390,7 +387,7 @@ async function _checkVaultKeyConsistency() {
   // compares — any mismatch (including ours after a losing race)
   // surfaces the drift.
   try {
-    await externalDb.query(
+    await externalDb().query(
       "INSERT INTO _blamejs_cluster_state " +
       "  (scope, vaultKeyFp, recordedAt, recordedByNode) " +
       "VALUES ('state', " +
@@ -413,7 +410,7 @@ async function _checkVaultKeyConsistency() {
 
   // Read whatever fingerprint is canonical (ours if first boot,
   // someone else's if we lost the race or are joining an existing cluster).
-  var rows = await externalDb.query(
+  var rows = await externalDb().query(
     "SELECT vaultKeyFp, recordedByNode, recordedAt FROM _blamejs_cluster_state " +
     "WHERE scope = 'state'",
     [],
@@ -619,7 +616,7 @@ function onTransition(handler) {
 async function shutdown() {
   if (!initialized) return;
   if (heartbeatTimer) {
-    clearInterval(heartbeatTimer);
+    heartbeatTimer.stop();
     heartbeatTimer = null;
   }
   if (lease) {
@@ -649,7 +646,7 @@ async function shutdown() {
 // ---- test helpers — not part of public contract ----
 
 function _resetForTest() {
-  if (heartbeatTimer) clearInterval(heartbeatTimer);
+  if (heartbeatTimer) heartbeatTimer.stop();
   heartbeatTimer = null;
   initialized = false;
   terminated = false;