@blamejs/core 0.9.46 → 0.9.49

package/lib/metrics.js

@@ -853,18 +853,43 @@ function snapshotRead(p) {
  * Format a snapshot object for human or machine consumption.
  *
  *   format: "text"       — operator-readable lines, one field per row (default)
- *   format: "prometheus" — Prometheus 0.0.4 text format, gauge metrics
- *                          named with a configurable prefix; only top-level
- *                          numeric fields under `snap.fields` are emitted
+ *   format: "prometheus" — Prometheus 0.0.4 text format
+ *
+ * ## Type detection (`prometheus` format only)
+ *
+ * Per Prometheus naming convention + OpenMetrics 1.0.0 §6.2, counter
+ * metric families MUST carry the `_total` suffix; every other numeric
+ * field renders as a gauge. The renderer auto-detects by suffix:
+ *
+ *   - field name ends in `_total` → `# TYPE <name> counter`
+ *   - everything else             → `# TYPE <name> gauge`
+ *
+ * Operators with metrics that don't fit the convention (e.g. a counter
+ * named `bytes_sent` without the `_total` suffix, or a gauge that
+ * happens to end in `_total`) opt the right type via `opts.fieldTypes`:
+ *
+ *   render(snap, { format: "prometheus", fieldTypes: {
+ *     bytes_sent: "counter",     // override default gauge
+ *     ratio_total: "gauge",       // override default counter
+ *   }});
+ *
+ * Pre-v0.9.47 every field rendered as gauge regardless of name, which
+ * broke `rate()` queries against counter-shaped series. Operators
+ * scraping a long-running deployment will see `rate(*_total[5m])`
+ * queries start returning the right answer once the new types reach
+ * the scrape target.
  *
  * @opts
- *   format:  "text" | "prometheus",   // default: "text"
- *   prefix:  string,                   // prometheus-only; default: "blamejs"
+ *   format:      "text" | "prometheus",   // default: "text"
+ *   prefix:      string,                   // prometheus-only; default: "blamejs"
+ *   fieldTypes:  Object,                   // prometheus-only; per-field type override
+ *                                          // map. Values: "counter" | "gauge".
  *
  * @example
  *   var snap = b.metrics.snapshot.read("/run/blamejs/metrics.json");
  *   process.stdout.write(b.metrics.snapshot.render(snap));
- *   // or for Prometheus scraping:
+ *   // or for Prometheus scraping (auto-detects http_requests_total
+ *   // as a counter via the _total suffix):
  *   res.setHeader("Content-Type", "text/plain; version=0.0.4");
  *   res.end(b.metrics.snapshot.render(snap, { format: "prometheus", prefix: "myapp" }));
  */
@@ -899,6 +924,11 @@ function snapshotRender(snap, opts) {
       throw new MetricsError("metrics-snapshot/bad-prefix",
         "metrics.snapshot.render: prometheus prefix must match [a-zA-Z_][a-zA-Z0-9_]*, got '" + prefix + "'");
     }
+    var fieldTypes = opts.fieldTypes || {};
+    if (typeof fieldTypes !== "object" || fieldTypes === null || Array.isArray(fieldTypes)) {
+      throw new MetricsError("metrics-snapshot/bad-field-types",
+        "metrics.snapshot.render: opts.fieldTypes must be an object mapping field-name → 'counter' | 'gauge'");
+    }
     var out = [];
     // allow:bare-canonicalize-walk — sort is for stable Prometheus
     // exposition output ordering, not canonicalize-for-hashing
@@ -909,7 +939,20 @@ function snapshotRender(snap, opts) {
       if (typeof v2 !== "number" || !isFinite(v2)) continue;   // only numeric scalars
       if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(k2)) continue;       // skip prom-incompatible names
       var metric = prefix + "_" + k2;
-      out.push("# TYPE " + metric + " gauge");
+      var declared = fieldTypes[k2];
+      var fieldType;
+      if (declared !== undefined) {
+        if (declared !== "counter" && declared !== "gauge") {
+          throw new MetricsError("metrics-snapshot/bad-field-type",
+            "metrics.snapshot.render: opts.fieldTypes." + k2 + " must be 'counter' or 'gauge', got '" + declared + "'");
+        }
+        fieldType = declared;
+      } else {
+        // Prometheus naming convention + OpenMetrics 1.0.0 §6.2:
+        // counter family names carry the _total suffix.
+        fieldType = /_total$/.test(k2) ? "counter" : "gauge";
+      }
+      out.push("# TYPE " + metric + " " + fieldType);
       out.push(metric + " " + v2);
     }
     return out.join("\n") + "\n";

package/lib/self-update.js

@@ -86,14 +86,41 @@ function _safeAuditEmit(action, outcome, metadata) {
 }
 
 // ---- semver-shaped comparison (tag_name like "v0.7.30" or "0.7.30") ----
-// Strips a leading "v" / "V" then parses dot-separated numeric components.
-// Non-numeric components are compared lexicographically (handles release
-// suffixes like "1.0.0-rc.1" by falling back to string comparison after
-// the matching numeric prefix). Returns -1 / 0 / +1.
 function _normalizeTag(tag) {
   if (typeof tag !== "string") return "";
   return tag.replace(/^v/i, "").trim();
 }
+
+/**
+ * @primitive b.selfUpdate.compareTags
+ * @signature b.selfUpdate.compareTags(a, b)
+ * @since     0.9.47
+ * @status    stable
+ *
+ * Compare two release tags / version strings. Returns `-1` if `a < b`,
+ * `+1` if `a > b`, `0` if equal. Strips a leading `v` / `V`, then walks
+ * dot-separated components: numeric pairs compared numerically; any
+ * non-numeric component (release suffixes like `1.0.0-rc.1`) falls back
+ * to lexicographic compare on that component. Missing components on
+ * either side are treated as `"0"`.
+ *
+ * Shape follows SemVer 2.0.0 §11 precedence rules for the numeric prefix.
+ * Deviations from the full SemVer §11 spec — pre-release identifiers
+ * (`-rc.1` < release) are compared lexicographically rather than the
+ * SemVer-mandated "alphanumeric identifiers compared as numbers if all
+ * numeric" rule. For most version-shaped strings the result is identical;
+ * exotic pre-release shapes (`1.0.0-alpha.10` vs `1.0.0-alpha.9`) sort
+ * lexicographically here (`10` < `9` as strings) rather than numerically.
+ * Operators with strict SemVer §11 needs should use a dedicated SemVer
+ * parser; this primitive targets the common framework-update polling
+ * shape (`v0.9.46` vs `v0.9.47`) where pre-release tags are rare.
+ *
+ * @example
+ *   b.selfUpdate.compareTags("v0.9.46", "v0.9.47");   // → -1
+ *   b.selfUpdate.compareTags("v0.9.47", "0.9.47");    // → 0  (leading "v" stripped)
+ *   b.selfUpdate.compareTags("1.10.0",  "1.9.0");     // → +1 (numeric, not lex)
+ *   b.selfUpdate.compareTags("v0.7.30", "v0.7.30");   // → 0
+ */
 function _compareTags(a, b) {
   var na = _normalizeTag(a);
   var nb2 = _normalizeTag(b);
@@ -648,6 +675,10 @@ module.exports = {
   SelfUpdateError:       SelfUpdateError,
   ALLOWED_HASH_ALGS:     ALLOWED_HASH_ALGS,
   DEFAULT_HASH_ALG:      DEFAULT_HASH_ALG,
+  // Public surface — same impl as the internal `_compareTags`;
+  // downstream consumers replacing one-off compareVersions helpers
+  // call this.
+  compareTags:           _compareTags,
   // Internal — exposed for the layer-0 test suite only.
   _compareTags:          _compareTags,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.9.46",
+  "version": "0.9.49",
   "description": "The Node framework that owns its stack.",
   "license": "Apache-2.0",
   "author": "blamejs contributors",

package/sbom.cdx.json

@@ -2,10 +2,10 @@
   "$schema": "http://cyclonedx.org/schema/bom-1.5.schema.json",
   "bomFormat": "CycloneDX",
   "specVersion": "1.6",
-  "serialNumber": "urn:uuid:c4e7762c-d190-47e8-9996-ee555a2414f8",
+  "serialNumber": "urn:uuid:21323cdb-5bfe-4b88-a63f-906795a497e6",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-15T23:01:46.269Z",
+    "timestamp": "2026-05-16T03:34:31.380Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.9.46",
+      "bom-ref": "@blamejs/core@0.9.49",
       "type": "library",
       "name": "blamejs",
-      "version": "0.9.46",
+      "version": "0.9.49",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.9.46",
+      "purl": "pkg:npm/%40blamejs/core@0.9.49",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.9.46",
+      "ref": "@blamejs/core@0.9.49",
       "dependsOn": []
     }
   ]