@blamejs/core 0.7.95 → 0.7.96

package/CHANGELOG.md

@@ -8,6 +8,8 @@ upgrading across more than a few patches at a time.
 
 ## v0.7.x
 
+- **0.7.96** (2026-05-06) — `b.observability.timed(name, fn, labels)` — convenience wrapper that measures wall-clock duration of a sync or async operation and emits a counter event carrying `duration_ms` in the labels alongside `outcome: "ok" | "fail"`. Returns the wrapped function's return value verbatim; rethrows on error after emitting the failure event with `error_type` capturing the thrown error's `.name`. Operators previously hand-rolled `var t0 = Date.now(); var r = await fn(); event(name, 1, { ...labels, duration_ms: Date.now() - t0, outcome: "ok" })` patterns at every call site — `timed` is the consolidated form. Composes with the existing `b.observability.SEMCONV` constants: `b.observability.timed("db.query", async () => db.query("SELECT ..."), { [SEMCONV.DB_OPERATION_NAME]: "select" })`. Operation name MUST be a stable string (not derived from input) to keep metric cardinality bounded; dynamic per-tenant labels go in the `labels` parameter.
+
 - **0.7.95** (2026-05-06) — `b.observability.SEMCONV` GenAI + cloud + container coverage. Twenty-eight new attribute names tracking OpenTelemetry semantic conventions for generative AI workloads, vector databases, cloud runtime context, and Kubernetes orchestration. **GenAI:** `GEN_AI_SYSTEM` / `GEN_AI_REQUEST_MODEL` / `GEN_AI_REQUEST_TEMPERATURE` / `GEN_AI_REQUEST_TOP_P` / `GEN_AI_REQUEST_TOP_K` / `GEN_AI_REQUEST_MAX_TOKENS` / `GEN_AI_REQUEST_STOP_SEQUENCES` / `GEN_AI_RESPONSE_MODEL` / `GEN_AI_RESPONSE_ID` / `GEN_AI_RESPONSE_FINISH_REASONS` / `GEN_AI_USAGE_INPUT_TOKENS` / `GEN_AI_USAGE_OUTPUT_TOKENS` / `GEN_AI_USAGE_TOTAL_TOKENS` / `GEN_AI_OPERATION_NAME` / `GEN_AI_TOOL_NAME` / `GEN_AI_TOOL_CALL_ID` / `GEN_AI_AGENT_ID` / `GEN_AI_AGENT_NAME` / `GEN_AI_AGENT_DESCRIPTION`. **Vector DB / RAG:** `DB_VECTOR_QUERY_TOP_K` / `DB_VECTOR_QUERY_DIMENSIONS` / `DB_VECTOR_QUERY_DISTANCE_METRIC`. **Cloud:** `CLOUD_PROVIDER` / `CLOUD_REGION` / `CLOUD_ACCOUNT_ID` / `CLOUD_RESOURCE_ID`. **Container / K8s:** `CONTAINER_ID` / `CONTAINER_IMAGE_NAME` / `CONTAINER_IMAGE_TAG` / `K8S_NAMESPACE_NAME` / `K8S_POD_NAME` / `K8S_DEPLOYMENT_NAME`. Operators wiring LLM client telemetry, vector-DB query traces, or Kubernetes-deployed services to an OTel collector reference these constants directly — string typos throw at access time instead of producing mis-named span attributes the OTel collector silently drops.
 
 - **0.7.94** (2026-05-06) — `b.compliance.REGIME_MAP` + `b.compliance.describe(<posture>)` — frozen lookup table mapping each posture name to its human-readable name + statutory citation + jurisdiction + domain. `b.compliance.describe("hipaa")` returns `{ name: "Health Insurance Portability and Accountability Act", citation: "Pub. L. 104-191; 45 CFR Parts 160, 162, 164", jurisdiction: "US", domain: "health" }`. Operators rendering the deployment posture in admin UI / audit logs reach for `REGIME_MAP[posture]` instead of hand-rolling a lookup table; values track the regulatory text and update with the framework rather than going stale in operator code. Covers all 19 postures shipped through v0.7.91 (hipaa / pci-dss / soc2 / sox + the v0.7.91 expansions: wmhmda / bipa / ccpa / gdpr / dora / nis2 / cra / ai-act / lgpd-br / pipl-cn / appi-jp / pdpa-sg / pipeda-ca / uk-gdpr). `domain` field categorizes the regime (privacy / health / payment / cybersecurity / financial-reporting / etc.) so operators can render compliance dashboards grouped by domain instead of alphabetical posture.

package/lib/observability.js

@@ -143,6 +143,57 @@ function safeEvent(name, value, labels) {
   catch (_e) { /* hot-path observability sink — drops silent on internal throws */ }
 }
 
+// timed — convenience wrapper that measures wall-clock duration of a
+// sync or async operation and emits a counter event with
+// duration_ms in the labels. Returns the wrapped function's return
+// value verbatim; rethrows on error after emitting the failure event
+// with outcome: "fail".
+//
+//   var rows = await b.observability.timed("db.query", async function () {
+//     return await db.query("SELECT * FROM users");
+//   }, { [SEMCONV.DB_OPERATION_NAME]: "select" });
+//
+// On success: emits `<name>` with { ...labels, outcome: "ok",
+// duration_ms }. On throw: emits with outcome: "fail".
+//
+// The operation name MUST be a stable string (not derived from input)
+// to keep the metric cardinality bounded; operators dynamically
+// scope-naming via prefix should use the labels parameter instead.
+function timed(name, fn, labels) {
+  if (typeof name !== "string" || name.length === 0) {
+    throw new TypeError("observability.timed: name must be a non-empty string");
+  }
+  if (typeof fn !== "function") {
+    throw new TypeError("observability.timed: fn must be a function");
+  }
+  var start = Date.now();
+  function _emit(outcome, extra) {
+    var allLabels = Object.assign({}, labels || {}, {
+      outcome:     outcome,
+      duration_ms: Date.now() - start,
+    }, extra || {});
+    try { event(name, 1, allLabels); }
+    catch (_e) { /* drop-silent — observability sink */ }
+  }
+  var ret;
+  try { ret = fn(); }
+  catch (e) {
+    _emit("fail", { error_type: (e && e.name) || "Error" });
+    throw e;
+  }
+  if (ret && typeof ret.then === "function") {
+    return ret.then(
+      function (v) { _emit("ok"); return v; },
+      function (e) {
+        _emit("fail", { error_type: (e && e.name) || "Error" });
+        throw e;
+      }
+    );
+  }
+  _emit("ok");
+  return ret;
+}
+
 // OpenTelemetry semantic-convention attribute names — the operator-
 // facing canonical vocabulary the framework's b.observability /
 // b.tracing / b.metrics emitters use when building span / metric
@@ -265,6 +316,7 @@ module.exports = {
   tap:        tap,
   event:      event,
   safeEvent:  safeEvent,
+  timed:      timed,
   setTap:     setTap,
   SEMCONV:    SEMCONV,
 };

package/package.json

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

package/sbom.cyclonedx.json

@@ -2,10 +2,10 @@
   "$schema": "http://cyclonedx.org/schema/bom-1.5.schema.json",
   "bomFormat": "CycloneDX",
   "specVersion": "1.5",
-  "serialNumber": "urn:uuid:3787e423-1b20-4099-9ab6-2794f46a4b23",
+  "serialNumber": "urn:uuid:f930dea4-02bf-424a-81d9-af05bce63d00",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-06T08:34:31.373Z",
+    "timestamp": "2026-05-06T08:44:44.540Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.7.95",
+      "bom-ref": "@blamejs/core@0.7.96",
       "type": "library",
       "name": "blamejs",
-      "version": "0.7.95",
+      "version": "0.7.96",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.7.95",
+      "purl": "pkg:npm/%40blamejs/core@0.7.96",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.7.95",
+      "ref": "@blamejs/core@0.7.96",
       "dependsOn": []
     }
   ]