@ultimat3/core 10.0.0 → 11.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/core",
-  "version": "10.0.0",
+  "version": "11.0.0",
   "description": "Ultimate's foundation: errors, context, env, config, clock, ids, logging, telemetry, lifecycle",
   "license": "MIT",
   "type": "module",

package/src/logger.ts

@@ -1,6 +1,7 @@
 // Single responsibility: structured JSON logging. One line per event, machine-readable by
 // default because the primary reader is an agent tailing `x logs --json`.
 
+import { assert } from './assert';
 import { type Clock, systemClock } from './clock';
 import { renderCauseValue } from './error-render';
 import { isUltimateError } from './errors';
@@ -244,8 +245,29 @@ function envLevel(): LogLevel {
     : 'info';
 }
 
+/**
+ * The level this logger enforces, refused when it is not one.
+ *
+ * `LEVEL_WEIGHT[level]` on anything else is `undefined`, and every `weight < undefined` is false —
+ * so the threshold failed OPEN and the logger emitted every line at every level. That is a `trace`
+ * stream out of a production process from one typo, which is the direction this read must never
+ * fail in. `LOG_LEVELS`, the same list `envLevel()` filters `LOG_LEVEL` through, because a level
+ * is typed here and arrives untyped: an `app.config.ts` value, a JSON file, a CLI flag.
+ */
+function resolveLevel(declared: LogLevel): LogLevel {
+  assert(
+    (LOG_LEVELS as readonly unknown[]).includes(declared),
+    // `renderCauseValue`, never `JSON.stringify`: it raises on a bigint and on a cycle, and a
+    // level that arrived from a config file can be either — the refusal must not be replaced by
+    // a `TypeError` from building its own message.
+    `${renderCauseValue(declared)} is not a log level`,
+    `pass one of ${LOG_LEVELS.join(', ')} to createLogger({ level })`,
+  );
+  return declared;
+}
+
 export function createLogger(options?: LoggerOptions): Logger {
-  const level = options?.level ?? envLevel();
+  const level = options?.level === undefined ? envLevel() : resolveLevel(options.level);
   const bound = options?.fields ?? {};
   const clock = options?.clock ?? systemClock;
   const writer = options?.writer ?? defaultWriter;

package/src/metrics.ts

@@ -174,14 +174,24 @@ export function resetMetrics(): void {
   }
 }
 
-/** Stable series key: attribute order must not create a second series for one label set. */
+/**
+ * Stable series key: attribute order must not create a second series for one label set, and no
+ * label set may spell another one's key.
+ *
+ * `JSON.stringify` over the sorted pairs, because a DELIMITER cannot carry the second property:
+ * the key was the pairs joined by control characters (U+0000 inside a pair, U+0001 between them),
+ * and a value holding those bytes IS another set's key — `{ a: 'b\u0001c\u0000d' }` was
+ * `{ a: 'b', c: 'd' }`, so the point landed on whichever series arrived first and was exported
+ * under labels the caller never passed. Attribute values are app data. Quoting is the only total
+ * answer and is not slower: 644 ns/op against the join's 709, on a 3-label set. `String(value)`
+ * stays, so `1` and `'1'` are still one series rather than two rows an exporter renders alike.
+ */
 function seriesKey(attributes: MetricAttributes): string {
   const entries = Object.entries(attributes);
   if (entries.length === 0) return '';
-  return entries
-    .sort(([a], [b]) => (a < b ? -1 : 1))
-    .map(([key, value]) => `${key}\u0000${String(value)}`)
-    .join('
');
+  return JSON.stringify(
+    entries.sort(([a], [b]) => (a < b ? -1 : 1)).map(([key, value]) => [key, String(value)]),
+  );
 }
 
 function finite(name: string, value: number): number {