@zerotal/telemetry 1.8.1 → 1.10.0

package/CHANGELOG.md

@@ -8,6 +8,16 @@ follows the Zerotal monorepo's unified versioning.
 
 ## [Unreleased]
 
+## [1.9.0] — 2026-08-29
+
+### Documented
+
+- **Every promised export is documented.** The `docs-coverage` gate reads `maturity: stable` as a
+  promise about a package's exports, and measures how much of that promise is written down. It
+  was 798 gaps across the suite; it is now zero. This package's share is covered on its own
+  pages — types named, options shapes described, and the decisions behind them recorded where
+  somebody looking for them will find them.
+
 ## [1.5.0] — 2026-08-15
 
 ### Added

package/api-surface.md

@@ -81,10 +81,10 @@ function TelemetryConfig = (options?: Partial<TelemetryConfigShape>) => Telemetr
 function withSpan = <T>(name: string, fn: (span: Span) => Promise<T>, options?: SpanOptions) => Promise<T>
 
 interface OtlpExporterOptions = {
-  endpoint?: string
-  headers?: Record<string, string>
-  serviceName?: string
-  serviceVersion?: string
+  endpoint?: string | undefined
+  headers?: Record<string, string> | undefined
+  serviceName?: string | undefined
+  serviceVersion?: string | undefined
 }
 
 interface SpanData = {
@@ -112,8 +112,8 @@ interface SpanExporter = {
 }
 
 interface SpanOptions = {
-  attributes?: Record<string, string | number | boolean>
-  kind?: SpanKind
+  attributes?: Record<string, string | number | boolean> | undefined
+  kind?: SpanKind | undefined
 }
 
 interface SpanStatus = {
@@ -122,21 +122,21 @@ interface SpanStatus = {
 }
 
 interface TelemetryConfigShape = {
-  exporter?: 'console' | 'noop' | 'otlp'
-  minDurationMs?: number
-  otlp?: {    endpoint?: string;    headers?: Record<string, string>;}
-  serviceName?: string
-  serviceVersion?: string
+  exporter?: 'console' | 'noop' | 'otlp' | undefined
+  minDurationMs?: number | undefined
+  otlp?: {    endpoint?: string;    headers?: Record<string, string>;} | undefined
+  serviceName?: string | undefined
+  serviceVersion?: string | undefined
 }
 
 interface TelemetryOptions = {
-  spanName?: (ctx: HttpContext) => string
+  spanName?: ((ctx: HttpContext) => string) | undefined
 }
 
 interface TracerOptions = {
   exporter: SpanExporter
-  minDurationMs?: number
-  rethrowExportErrors?: boolean
+  minDurationMs?: number | undefined
+  rethrowExportErrors?: boolean | undefined
 }
 
 type SpanKind = 'internal' | 'server' | 'client' | 'producer' | 'consumer'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zerotal/telemetry",
-  "version": "1.8.1",
+  "version": "1.10.0",
   "license": "MIT",
   "maturity": "stable",
   "private": false,
@@ -30,7 +30,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@zerotal/core": "1.8.1"
+    "@zerotal/core": "1.10.0"
   },
   "devDependencies": {
     "typescript": "^5.8.0"

package/src/Tracer.ts

@@ -6,14 +6,14 @@ import type { SpanExporter } from "./exporters/SpanExporter.ts";
 export interface TracerOptions {
   exporter: SpanExporter;
   /** Drop spans in which the callback took less than this many ms. Default: 0 (keep all). */
-  minDurationMs?: number;
+  minDurationMs?: number | undefined;
   /** When true, export() errors are surfaced rather than swallowed. Default: false. */
-  rethrowExportErrors?: boolean;
+  rethrowExportErrors?: boolean | undefined;
 }
 
 export interface SpanOptions {
-  kind?: SpanKind;
-  attributes?: Record<string, string | number | boolean>;
+  kind?: SpanKind | undefined;
+  attributes?: Record<string, string | number | boolean> | undefined;
 }
 
 /**

package/src/config.ts

@@ -7,22 +7,24 @@ export interface TelemetryConfigShape {
    * - `'console'` - prints to stdout, useful in development
    * - `'otlp'`    - sends to an OTLP HTTP endpoint
    */
-  exporter?: "noop" | "console" | "otlp";
+  exporter?: "noop" | "console" | "otlp" | undefined;
 
   /** Only relevant when `exporter` is `'otlp'`. */
-  otlp?: {
-    endpoint?: string;
-    headers?: Record<string, string>;
-  };
+  otlp?:
+    | {
+        endpoint?: string;
+        headers?: Record<string, string>;
+      }
+    | undefined;
 
   /** Service name sent as a resource attribute. Defaults to `APP_NAME` env var or `'zerotal-app'`. */
-  serviceName?: string;
+  serviceName?: string | undefined;
 
   /** Service version. Defaults to `APP_VERSION` env var or `'0.0.0'`. */
-  serviceVersion?: string;
+  serviceVersion?: string | undefined;
 
   /** Drop spans shorter than this many milliseconds. Default: 0 (keep all). */
-  minDurationMs?: number;
+  minDurationMs?: number | undefined;
 }
 
 const defaults: TelemetryConfigShape = {

package/src/exporters/OtlpExporter.ts

@@ -3,13 +3,13 @@ import type { SpanData, SpanKind } from "../Span.ts";
 
 export interface OtlpExporterOptions {
   /** OTLP HTTP/JSON endpoint. Default: `'http://localhost:4318/v1/traces'`. */
-  endpoint?: string;
+  endpoint?: string | undefined;
   /** Extra headers (e.g. `{ 'x-honeycomb-team': '<api-key>' }`). */
-  headers?: Record<string, string>;
+  headers?: Record<string, string> | undefined;
   /** Service name sent as a resource attribute. */
-  serviceName?: string;
+  serviceName?: string | undefined;
   /** Service version sent as a resource attribute. */
-  serviceVersion?: string;
+  serviceVersion?: string | undefined;
 }
 
 const SPAN_KIND: Record<SpanKind, number> = {

package/src/middleware/TelemetryMiddleware.ts

@@ -8,7 +8,7 @@ export interface TelemetryOptions {
    * Custom function to derive a span name from the request.
    * Default: `"${method} ${pathname}"`.
    */
-  spanName?: (ctx: HttpContext) => string;
+  spanName?: ((ctx: HttpContext) => string) | undefined;
 }
 
 /**