@blamejs/core 0.8.42 → 0.8.49

package/lib/tracing.js

@@ -1,84 +1,41 @@
 "use strict";
 /**
- * tracing — OpenTelemetry seam without an OTel runtime dependency.
+ * @module b.tracing
+ * @nav    Observability
+ * @title  Tracing
  *
- * The framework doesn't bundle the OTel SDK — operators install
- * `@opentelemetry/api` (and an exporter) themselves when they want
- * tracing. This module:
+ * @intro
+ *   Distributed-tracing seam — W3C trace-context propagation,
+ *   OpenTelemetry-shaped span lifecycle, sampling routed through OTel
+ *   when installed.
  *
- *   - Detects if @opentelemetry/api is installed (try/catch require,
- *     cached). When it's there, every framework span call routes into
- *     OTel's real tracer and shows up in the operator's exporter
- *     (Jaeger, Zipkin, OTLP, console, whatever they wired).
- *   - When OTel ISN'T installed, every call is a pass-through. The
- *     wrapped function still executes, return values still propagate,
- *     thrown errors still escape — but no span is created and no
- *     overhead is paid beyond one cached lookup.
+ *   The framework keeps zero npm runtime deps, so the OTel SDK isn't
+ *   bundled. `b.tracing.create()` detects `@opentelemetry/api` at
+ *   first use: when it's installed, every span call flows into the
+ *   operator's tracer (Jaeger / Zipkin / OTLP / console — whatever
+ *   exporter they wired) and OTel's sampler decides per-span
+ *   `sampled` flag from the configured `TraceIdRatioBased` /
+ *   `ParentBased` rules. When OTel is absent every call falls through
+ *   a pass-through tracer that still executes the wrapped function,
+ *   propagates return values and exceptions, and emits no span data.
  *
- * Public API:
+ *   `contextHeaders()` and `extractContext()` always parse and emit
+ *   the W3C `traceparent` format
+ *   (`00-<32-hex traceId>-<16-hex spanId>-<2-hex flags>`) regardless
+ *   of whether OTel is loaded — so operators get trace-ID per request
+ *   as a free correlation baseline even without a tracer SDK. Span
+ *   shape mirrors OTel: `setAttribute` / `addEvent` /
+ *   `recordException` / `setStatus` / `end` / `updateName`.
  *
- *   var t = b.tracing.create({
- *     instrumentationName:    "blamejs",
- *     instrumentationVersion: "1.0.0",
- *   });
+ *   `b.tracing.tap("audit.record", attributes, fn)` mirrors
+ *   `b.metrics.tap` for tracing — wraps `fn` in a span if a registry
+ *   is active, passes through otherwise. `requestMiddleware()` opens
+ *   one span per inbound request, extracts any incoming
+ *   `traceparent`, and promotes `http.route` to the matched route
+ *   template at response time.
  *
- *   // Wrap async work in a span. Returns whatever fn returns.
- *   var result = await t.span("my-op", async function (span) {
- *     span.setAttribute("user_id", "abc");
- *     span.addEvent("cache-miss");
- *     return await doWork();
- *   }, { kind: "internal", attributes: { route: "/users" } });
- *
- *   // Sync variant.
- *   var x = t.spanSync("compute", function (span) { ... return v; });
- *
- *   // Read / write the current active span.
- *   t.currentSpan();                          // null when no active span
- *   t.setAttributes({ user_id: "abc" });      // sets on current
- *   t.recordException(err);                   // records on current
- *
- *   // HTTP propagation. contextHeaders() returns headers to add to
- *   // outbound requests (W3C `traceparent`); extractContext(headers)
- *   // pulls a parent context from inbound headers.
- *   var headers = t.contextHeaders();
- *   var parentCtx = t.extractContext(req.headers);
- *
- *   // Auto-span request middleware — wraps each handler in a span
- *   // named after method + route pattern.
- *   router.use(t.requestMiddleware());
- *
- *   // Framework-internal hot-path tap — wraps fn in a span named
- *   // `name` if a registry is active; pass-through otherwise. Like
- *   // metrics.tap() but for tracing instead of counting.
- *   b.tracing.tap("audit.record", attributes, fn);
- *
- * Even WITHOUT @opentelemetry/api installed:
- *   - contextHeaders() / extractContext() still parse and emit the
- *     W3C traceparent format. So a framework process without OTel
- *     can still propagate trace IDs through logs and HTTP for
- *     correlation, even without span telemetry. Operators get the
- *     "trace ID per request" plumbing as a free baseline.
- *   - currentSpan() returns a minimal pass-through "span" object so
- *     operator code can call setAttribute / addEvent / recordException
- *     unconditionally — they're no-ops without OTel.
- *
- * Why no @otel runtime dep:
- *   - The framework keeps zero npm runtime deps. Apps that want tracing
- *     install OTel themselves; apps that don't pay nothing.
- *   - The OTel API is unstable enough that pinning a vendored version
- *     would create more churn than it saves.
- *
- * Out of scope (with structural reasons):
- *   - Vendoring the SDK: see above.
- *   - Sampling decisions: OTel handles this when wired; without OTel
- *     there's nothing to sample.
- *   - Exporter integration: belongs to the OTel SDK, not the framework.
- *   - Custom propagators: framework ships W3C traceparent only. OTel
- *     adds others (b3, jaeger) when wired by the operator.
- *   - Async-context propagation across setTimeout / setImmediate:
- *     OTel's NodeSDK auto-instrumentation handles this when installed;
- *     without OTel, framework code uses fn-passing rather than
- *     async-context, which is fine for the surfaces we instrument.
+ * @card
+ *   Distributed-tracing seam — W3C trace-context propagation, OpenTelemetry-shaped span lifecycle, sampling routed through OTel when installed.
  */
 
 var C = require("./constants");
@@ -205,6 +162,42 @@ function _passthroughTracer() {
 
 // ---- Registry factory ----
 
+/**
+ * @primitive b.tracing.create
+ * @signature b.tracing.create(opts)
+ * @since     0.4.0
+ * @status    stable
+ * @related   b.tracing.tap, b.metrics.create, b.observability.tap
+ *
+ * Build a tracing registry. The returned registry exposes `span`,
+ * `spanSync`, `currentSpan`, `setAttributes`, `recordException`,
+ * `contextHeaders` / `extractContext` for W3C traceparent
+ * propagation, `requestMiddleware()` for per-request auto-spans, and
+ * `tap()` for framework hot-path wrapping. Detects
+ * `@opentelemetry/api` once at first use; without OTel installed the
+ * registry runs in pass-through mode but still propagates trace IDs
+ * over HTTP.
+ *
+ * @opts
+ *   instrumentationName:    string,  // OTel tracer name; default "blamejs"
+ *   instrumentationVersion: string,  // OTel tracer version; default "0.0.0"
+ *
+ * @example
+ *   var t = b.tracing.create({
+ *     instrumentationName:    "myapp",
+ *     instrumentationVersion: "1.2.3",
+ *   });
+ *
+ *   var users = await t.span("load-users", async function (span) {
+ *     span.setAttribute("user_id", "abc");
+ *     span.addEvent("cache-miss");
+ *     return await db.query("SELECT id, email FROM users");
+ *   }, { kind: "internal", attributes: { route: "/users" } });
+ *
+ *   // Outbound — propagate the active trace.
+ *   var headers = t.contextHeaders();
+ *   // → { traceparent: "00-<32 hex>-<16 hex>-01" } when a span is active
+ */
 function create(opts) {
   opts = opts || {};
   validateOpts(opts, [
@@ -461,6 +454,29 @@ function create(opts) {
 
 var _globalRegistry = null;
 
+/**
+ * @primitive b.tracing.tap
+ * @signature b.tracing.tap(name, attributes, fn)
+ * @since     0.4.0
+ * @related   b.tracing.create, b.metrics.tap, b.observability.tap
+ *
+ * Framework hot-path tracing tap. Modules call
+ * `tap("audit.record", { action: "login" }, fn)` without importing a
+ * registry. Until `b.tracing.create()` runs the call passes `fn(null)`
+ * through directly (zero overhead, no span); afterwards the active
+ * registry wraps `fn` in a span named `name` with the supplied
+ * attributes. The two-arg form `tap(name, fn)` is permitted when no
+ * attributes are needed.
+ *
+ * @example
+ *   // Module-level — passthrough until a registry exists.
+ *   var rows = b.tracing.tap("db.query", { table: "users" }, function () {
+ *     return db.queryAll("SELECT id FROM users");
+ *   });
+ *
+ *   // Two-arg — no attributes:
+ *   b.tracing.tap("queue.enqueue", function () { return enqueueJob(); });
+ */
 function tap(name, attributes, fn) {
   if (typeof attributes === "function") {
     fn = attributes; attributes = null;

package/lib/uuid.js

@@ -1,32 +1,30 @@
 "use strict";
 /**
- * uuid — RFC 4122 v4 (random) + RFC 9562 v7 (time-ordered).
+ * @module b.uuid
+ * @featured true
+ * @nav    Tools
+ * @title  UUID
  *
- * Two flavors:
+ * @intro
+ *   RFC 4122 v4 (random) + RFC 9562 v7 (time-ordered).
  *
- *   b.uuid.v4()           — fully random 128-bit UUID. Standard, portable,
- *                           the default choice when ordering doesn't matter.
+ *   v4 is fully random — the standard portable choice when ordering
+ *   doesn't matter. v7 prefixes a 48-bit Unix-millisecond timestamp,
+ *   then 74 random bits — IDs sort by creation time even
+ *   lexicographically, ideal as a database PK because B-tree inserts
+ *   stay near the right edge.
  *
- *   b.uuid.v7()           — Unix-millisecond timestamp prefix + 74 random
- *                           bits. Time-ordered (sorts by creation time even
- *                           lexicographically), ideal as a database PK
- *                           because B-tree inserts stay near the right edge
- *                           — no random scattering across the index.
+ *   All entropy comes from `b.crypto.generateBytes`, which routes
+ *   through Node's `crypto.randomBytes` — same source as
+ *   `crypto.randomUUID()`.
  *
- *   b.uuid.parse(str)     — { ok, version, bytes }. Validates the canonical
- *                           8-4-4-4-12 hex form and the version + variant
- *                           bits. Returns ok:false (no throw) on bad input.
+ *   Why ship v7 ourselves? Native `crypto.randomUUID()` only emits
+ *   v4. v7 is the modern recommendation for any UUID landing in a
+ *   sortable column (job queues, audit chain extensions, anything
+ *   where insertion order matters for index locality).
  *
- *   b.uuid.isValid(str)   — boolean shorthand. No version/variant check
- *                           beyond shape — operators who care use parse().
- *
- * All entropy comes from `b.crypto.generateBytes`, which routes through
- * `node:crypto.randomBytes` — same source as `crypto.randomUUID()`.
- *
- * Why ship v7 ourselves? Native `crypto.randomUUID()` only emits v4.
- * v7 is the modern recommendation for any UUID landing in a sortable
- * column (jobs queue, audit chain extensions, anything where insertion
- * order matters for index locality).
+ * @card
+ *   RFC 4122 v4 (random) + RFC 9562 v7 (time-ordered).
  */
 var C = require("./constants");
 var { generateBytes } = require("./crypto");
@@ -67,6 +65,20 @@ function _bytesToString(bytes) {
          hex.slice(HEX_CLOCK_SEQ_END, HEX_NODE_END);
 }
 
+/**
+ * @primitive b.uuid.v4
+ * @signature b.uuid.v4()
+ * @since     0.1.0
+ * @related   b.uuid.v7, b.uuid.parse
+ *
+ * Fully random 128-bit UUID. Standard, portable; the default choice
+ * when ordering doesn't matter. Returns the canonical 8-4-4-4-12
+ * hex form.
+ *
+ * @example
+ *   var id = b.uuid.v4();
+ *   // → "f47ac10b-58cc-4372-a567-0e02b2c3d479"
+ */
 function v4() {
   var b = generateBytes(UUID_BYTE_LEN);
   // version = 4 (0100): high nibble of byte 6
@@ -76,6 +88,34 @@ function v4() {
   return _bytesToString(b);
 }
 
+/**
+ * @primitive b.uuid.v7
+ * @signature b.uuid.v7(opts?)
+ * @since     0.4.0
+ * @related   b.uuid.v4, b.uuid.parse
+ *
+ * RFC 9562 §5.7 time-ordered UUID. The first 48 bits encode a Unix
+ * millisecond timestamp (big-endian); the next 4 bits are version (7);
+ * the remaining 74 bits are random. IDs generated within the same
+ * millisecond sort by their random suffix; across milliseconds they
+ * sort by time. B-tree index locality is dramatically better than v4
+ * for INSERT-heavy tables.
+ *
+ * @opts
+ *   now: number,   // override the timestamp (testing / fixtures)
+ *
+ * @example
+ *   var id = b.uuid.v7();
+ *   // → "01941bf3-9c4a-7d8e-9c11-3a4b5c6d7e8f"
+ *
+ *   // Deterministic fixture: same ms produces the same time prefix.
+ *   var fixed = b.uuid.v7({ now: Date.UTC(2026, 0, 1) });
+ *
+ *   // v7 sorts by time even as plain strings:
+ *   var earlier = b.uuid.v7({ now: 1700000000000 });
+ *   var later   = b.uuid.v7({ now: 1700000001000 });
+ *   earlier < later;   // → true
+ */
 function v7(opts) {
   // RFC 9562 §5.7 layout:
   //   bytes 0-5  : 48-bit big-endian Unix timestamp in milliseconds
@@ -101,6 +141,27 @@ function v7(opts) {
   return _bytesToString(b);
 }
 
+/**
+ * @primitive b.uuid.parse
+ * @signature b.uuid.parse(str)
+ * @since     0.1.0
+ * @related   b.uuid.isValid
+ *
+ * Strict parse: validates canonical form AND version (1-7) AND
+ * RFC 4122 variant. Returns `{ ok: true, version, bytes }` on success;
+ * `{ ok: false, reason }` on failure. Never throws — operators who
+ * want a thrown error layer one on top.
+ *
+ * @example
+ *   var parsed = b.uuid.parse("f47ac10b-58cc-4372-a567-0e02b2c3d479");
+ *   if (parsed.ok) {
+ *     console.log(parsed.version);   // → 4
+ *     console.log(parsed.bytes);     // → <Buffer f4 7a c1 0b ...>
+ *   }
+ *
+ *   b.uuid.parse("not-a-uuid").ok;       // → false
+ *   b.uuid.parse("not-a-uuid").reason;   // → "malformed"
+ */
 function parse(str) {
   if (typeof str !== "string") return { ok: false, reason: "not-a-string" };
   // Length cap before regex — RFC 4122 canonical form is exactly 36
@@ -118,6 +179,20 @@ function parse(str) {
   return { ok: true, version: version, bytes: bytes };
 }
 
+/**
+ * @primitive b.uuid.isValid
+ * @signature b.uuid.isValid(str)
+ * @since     0.1.0
+ * @related   b.uuid.parse
+ *
+ * Loose shape-only check — returns `true` for any 8-4-4-4-12 hex
+ * string regardless of version or variant bits. Cheap. Use `parse()`
+ * when version/variant matter (most operator code does).
+ *
+ * @example
+ *   b.uuid.isValid("f47ac10b-58cc-4372-a567-0e02b2c3d479");   // → true
+ *   b.uuid.isValid("not-a-uuid");                             // → false
+ */
 function isValid(str) {
   if (typeof str !== "string") return false;
   if (str.length > UUID_STR_MAX_LEN) return false;