@gobing-ai/ts-infra 0.3.0 → 0.3.2

package/dist/telemetry/metrics.d.ts

@@ -4,20 +4,39 @@
  */
 import { type Counter, type Histogram } from '@opentelemetry/api';
 export type { Counter, Histogram } from '@opentelemetry/api';
+/** Whether the metrics subsystem has been initialized via {@link initMetrics}. */
 export declare function isMetricsInitialized(): boolean;
+/** Counter for total outbound HTTP requests, tagged by method and status code. */
 export declare function getHttpClientRequestTotal(): Counter;
+/** Histogram for outbound HTTP request duration in milliseconds. */
 export declare function getHttpClientRequestDuration(): Histogram;
+/** Counter for outbound HTTP errors, tagged by error type. */
 export declare function getHttpClientRequestErrors(): Counter;
+/** Counter for total event bus emits. */
 export declare function getEventbusEmitsTotal(): Counter;
+/** Counter for event bus handler errors. */
 export declare function getEventbusErrorsTotal(): Counter;
+/** Counter for total jobs enqueued. */
 export declare function getQueueJobEnqueuedTotal(): Counter;
+/** Counter for total jobs completed successfully. */
 export declare function getQueueJobCompletedTotal(): Counter;
+/** Counter for total jobs that failed (exhausted retries). */
 export declare function getQueueJobFailedTotal(): Counter;
+/** Histogram for job processing duration in milliseconds. */
 export declare function getQueueJobProcessingDuration(): Histogram;
+/** Counter for total scheduled job executions. */
 export declare function getSchedulerJobExecutedTotal(): Counter;
+/** Histogram for scheduled job execution duration in milliseconds. */
 export declare function getSchedulerJobDuration(): Histogram;
+/** Counter for failed scheduled job executions. */
 export declare function getSchedulerJobFailedTotal(): Counter;
+/** Mark the metrics subsystem as initialized. Idempotent. */
 export declare function initMetrics(): void;
+/** Clear the instrument cache and mark metrics as uninitialized. */
 export declare function shutdownMetrics(): Promise<void>;
+/**
+ * Reset all metrics state: clear instrument cache, mark uninitialized,
+ * and disable the global meter. For testing only.
+ */
 export declare function _resetMetrics(): void;
 //# sourceMappingURL=metrics.d.ts.map

package/dist/telemetry/metrics.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"metrics.d.ts","sourceRoot":"","sources":["../../src/telemetry/metrics.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,KAAK,OAAO,EAAE,KAAK,SAAS,EAAW,MAAM,oBAAoB,CAAC;AAE3E,YAAY,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAI7D,wBAAgB,oBAAoB,IAAI,OAAO,CAE9C;AA8BD,wBAAgB,yBAAyB,IAAI,OAAO,CAEnD;AAED,wBAAgB,4BAA4B,IAAI,SAAS,CAExD;AAED,wBAAgB,0BAA0B,IAAI,OAAO,CAEpD;AAID,wBAAgB,qBAAqB,IAAI,OAAO,CAE/C;AAED,wBAAgB,sBAAsB,IAAI,OAAO,CAEhD;AAID,wBAAgB,wBAAwB,IAAI,OAAO,CAElD;AAED,wBAAgB,yBAAyB,IAAI,OAAO,CAEnD;AAED,wBAAgB,sBAAsB,IAAI,OAAO,CAEhD;AAED,wBAAgB,6BAA6B,IAAI,SAAS,CAEzD;AAID,wBAAgB,4BAA4B,IAAI,OAAO,CAEtD;AAED,wBAAgB,uBAAuB,IAAI,SAAS,CAEnD;AAED,wBAAgB,0BAA0B,IAAI,OAAO,CAEpD;AAID,wBAAgB,WAAW,IAAI,IAAI,CAGlC;AAED,wBAAgB,eAAe,IAAI,OAAO,CAAC,IAAI,CAAC,CAS/C;AAED,wBAAgB,aAAa,IAAI,IAAI,CAMpC"}
+{"version":3,"file":"metrics.d.ts","sourceRoot":"","sources":["../../src/telemetry/metrics.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,KAAK,OAAO,EAAE,KAAK,SAAS,EAAW,MAAM,oBAAoB,CAAC;AAE3E,YAAY,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAI7D,kFAAkF;AAClF,wBAAgB,oBAAoB,IAAI,OAAO,CAE9C;AA8BD,kFAAkF;AAClF,wBAAgB,yBAAyB,IAAI,OAAO,CAEnD;AAED,oEAAoE;AACpE,wBAAgB,4BAA4B,IAAI,SAAS,CAExD;AAED,8DAA8D;AAC9D,wBAAgB,0BAA0B,IAAI,OAAO,CAEpD;AAID,yCAAyC;AACzC,wBAAgB,qBAAqB,IAAI,OAAO,CAE/C;AAED,4CAA4C;AAC5C,wBAAgB,sBAAsB,IAAI,OAAO,CAEhD;AAID,uCAAuC;AACvC,wBAAgB,wBAAwB,IAAI,OAAO,CAElD;AAED,qDAAqD;AACrD,wBAAgB,yBAAyB,IAAI,OAAO,CAEnD;AAED,8DAA8D;AAC9D,wBAAgB,sBAAsB,IAAI,OAAO,CAEhD;AAED,6DAA6D;AAC7D,wBAAgB,6BAA6B,IAAI,SAAS,CAEzD;AAID,kDAAkD;AAClD,wBAAgB,4BAA4B,IAAI,OAAO,CAEtD;AAED,sEAAsE;AACtE,wBAAgB,uBAAuB,IAAI,SAAS,CAEnD;AAED,mDAAmD;AACnD,wBAAgB,0BAA0B,IAAI,OAAO,CAEpD;AAID,6DAA6D;AAC7D,wBAAgB,WAAW,IAAI,IAAI,CAGlC;AAED,oEAAoE;AACpE,wBAAgB,eAAe,IAAI,OAAO,CAAC,IAAI,CAAC,CAS/C;AAED;;;GAGG;AACH,wBAAgB,aAAa,IAAI,IAAI,CAMpC"}

package/dist/telemetry/metrics.js

@@ -4,6 +4,7 @@
  */
 import { metrics } from '@opentelemetry/api';
 let metricsInitialized = false;
+/** Whether the metrics subsystem has been initialized via {@link initMetrics}. */
 export function isMetricsInitialized() {
     return metricsInitialized;
 }
@@ -28,51 +29,65 @@ function getOrCreateHistogram(key, name, description, unit = 'ms') {
     return instruments[key];
 }
 // ── HTTP client ─────────────────────────────────────────────────────
+/** Counter for total outbound HTTP requests, tagged by method and status code. */
 export function getHttpClientRequestTotal() {
     return getOrCreateCounter('httpCliReq', 'http.client.request.total', 'Total outbound HTTP requests', '{request}');
 }
+/** Histogram for outbound HTTP request duration in milliseconds. */
 export function getHttpClientRequestDuration() {
     return getOrCreateHistogram('httpCliDur', 'http.client.request.duration', 'Outbound HTTP request duration');
 }
+/** Counter for outbound HTTP errors, tagged by error type. */
 export function getHttpClientRequestErrors() {
     return getOrCreateCounter('httpCliErr', 'http.client.request.errors', 'Outbound HTTP errors', '{error}');
 }
 // ── Event bus ───────────────────────────────────────────────────────
+/** Counter for total event bus emits. */
 export function getEventbusEmitsTotal() {
     return getOrCreateCounter('ebEmit', 'eventbus.emits.total', 'Total event bus emits', '{emit}');
 }
+/** Counter for event bus handler errors. */
 export function getEventbusErrorsTotal() {
     return getOrCreateCounter('ebErr', 'eventbus.errors.total', 'Event bus errors', '{error}');
 }
 // ── Queue ───────────────────────────────────────────────────────────
+/** Counter for total jobs enqueued. */
 export function getQueueJobEnqueuedTotal() {
     return getOrCreateCounter('qEnq', 'queue.jobs.enqueued', 'Total jobs enqueued', '{job}');
 }
+/** Counter for total jobs completed successfully. */
 export function getQueueJobCompletedTotal() {
     return getOrCreateCounter('qComp', 'queue.jobs.completed', 'Total jobs completed', '{job}');
 }
+/** Counter for total jobs that failed (exhausted retries). */
 export function getQueueJobFailedTotal() {
     return getOrCreateCounter('qFail', 'queue.jobs.failed', 'Total jobs failed', '{job}');
 }
+/** Histogram for job processing duration in milliseconds. */
 export function getQueueJobProcessingDuration() {
     return getOrCreateHistogram('qProcDur', 'queue.jobs.processing_duration', 'Job processing duration');
 }
 // ── Scheduler ───────────────────────────────────────────────────────
+/** Counter for total scheduled job executions. */
 export function getSchedulerJobExecutedTotal() {
     return getOrCreateCounter('schedExec', 'scheduler.jobs.executed', 'Total scheduled job executions', '{execution}');
 }
+/** Histogram for scheduled job execution duration in milliseconds. */
 export function getSchedulerJobDuration() {
     return getOrCreateHistogram('schedDur', 'scheduler.jobs.duration', 'Scheduled job duration');
 }
+/** Counter for failed scheduled job executions. */
 export function getSchedulerJobFailedTotal() {
     return getOrCreateCounter('schedFail', 'scheduler.jobs.failed', 'Failed scheduled jobs', '{failure}');
 }
 // ── Lifecycle ───────────────────────────────────────────────────────
+/** Mark the metrics subsystem as initialized. Idempotent. */
 export function initMetrics() {
     if (metricsInitialized)
         return;
     metricsInitialized = true;
 }
+/** Clear the instrument cache and mark metrics as uninitialized. */
 export function shutdownMetrics() {
     // The meter provider is owned by whoever registered it globally (the host
     // app or `@gobing-ai/ts-infra/otel-node`). Here we only drop the instrument
@@ -83,6 +98,10 @@ export function shutdownMetrics() {
     metricsInitialized = false;
     return Promise.resolve();
 }
+/**
+ * Reset all metrics state: clear instrument cache, mark uninitialized,
+ * and disable the global meter. For testing only.
+ */
 export function _resetMetrics() {
     for (const key of Object.keys(instruments)) {
         instruments[key] = undefined;

package/dist/telemetry/sdk.d.ts

@@ -9,16 +9,20 @@
  */
 import { type Tracer } from '@opentelemetry/api';
 import type { TelemetryConfig } from './config';
+/** Get the resolved telemetry configuration (defaults + overrides). */
 export declare function getResolvedConfig(): TelemetryConfig;
 /**
  * Resolve telemetry config and mark telemetry enabled. Does not register any
  * provider — spans flow to the globally-registered provider (none ⇒ no-op).
  */
 export declare function initTelemetry(config?: Partial<TelemetryConfig>): void;
+/** Mark telemetry as uninitialized. Does not shut down the OTel provider. */
 export declare function shutdownTelemetry(): Promise<void>;
 /** The infra tracer from the globally-registered provider (no-op when none). */
 export declare function getTracer(): Tracer;
+/** Whether telemetry is initialized and enabled. */
 export declare function isTelemetryEnabled(): boolean;
+/** Reset the telemetry subsystem to its uninitialized state. For testing. */
 export declare function _resetTelemetry(): void;
 export { context, propagation, trace } from '@opentelemetry/api';
 //# sourceMappingURL=sdk.d.ts.map

package/dist/telemetry/sdk.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sdk.d.ts","sourceRoot":"","sources":["../../src/telemetry/sdk.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAE,KAAK,MAAM,EAAS,MAAM,oBAAoB,CAAC;AACxD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAShD,wBAAgB,iBAAiB,IAAI,eAAe,CAEnD;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,eAAe,CAAC,GAAG,IAAI,CAIrE;AAED,wBAAgB,iBAAiB,IAAI,OAAO,CAAC,IAAI,CAAC,CAGjD;AAED,gFAAgF;AAChF,wBAAgB,SAAS,IAAI,MAAM,CAElC;AAED,wBAAgB,kBAAkB,IAAI,OAAO,CAE5C;AAED,wBAAgB,eAAe,IAAI,IAAI,CAGtC;AAED,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"sdk.d.ts","sourceRoot":"","sources":["../../src/telemetry/sdk.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAE,KAAK,MAAM,EAAS,MAAM,oBAAoB,CAAC;AACxD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAShD,uEAAuE;AACvE,wBAAgB,iBAAiB,IAAI,eAAe,CAEnD;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,eAAe,CAAC,GAAG,IAAI,CAIrE;AAED,6EAA6E;AAC7E,wBAAgB,iBAAiB,IAAI,OAAO,CAAC,IAAI,CAAC,CAGjD;AAED,gFAAgF;AAChF,wBAAgB,SAAS,IAAI,MAAM,CAElC;AAED,oDAAoD;AACpD,wBAAgB,kBAAkB,IAAI,OAAO,CAE5C;AAED,6EAA6E;AAC7E,wBAAgB,eAAe,IAAI,IAAI,CAGtC;AAED,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/telemetry/sdk.js

@@ -13,6 +13,7 @@ const TRACER_NAME = '@gobing-ai/ts-infra';
 const TRACER_VERSION = '0.1.0';
 let telemetryInitialized = false;
 let resolvedConfig = getTelemetryConfig();
+/** Get the resolved telemetry configuration (defaults + overrides). */
 export function getResolvedConfig() {
     return resolvedConfig;
 }
@@ -26,6 +27,7 @@ export function initTelemetry(config) {
     resolvedConfig = { ...getTelemetryConfig(), ...config };
     telemetryInitialized = true;
 }
+/** Mark telemetry as uninitialized. Does not shut down the OTel provider. */
 export function shutdownTelemetry() {
     telemetryInitialized = false;
     return Promise.resolve();
@@ -34,9 +36,11 @@ export function shutdownTelemetry() {
 export function getTracer() {
     return trace.getTracer(TRACER_NAME, TRACER_VERSION);
 }
+/** Whether telemetry is initialized and enabled. */
 export function isTelemetryEnabled() {
     return telemetryInitialized && resolvedConfig.enabled;
 }
+/** Reset the telemetry subsystem to its uninitialized state. For testing. */
 export function _resetTelemetry() {
     telemetryInitialized = false;
     resolvedConfig = getTelemetryConfig();

package/dist/telemetry/tracing.d.ts

@@ -2,11 +2,23 @@
  * High-level tracing helpers for application code.
  */
 import { type Span, type SpanOptions, type Tracer } from '@opentelemetry/api';
+/**
+ * Execute an async function within an active OTel span.
+ * The span is automatically ended and its status set on error.
+ */
 export declare function traceAsync<T>(name: string, fn: (span: Span) => Promise<T>, options?: SpanOptions, tracer?: Tracer): Promise<T>;
+/**
+ * Execute a synchronous function within an active OTel span.
+ * The span is automatically ended and its status set on error.
+ */
 export declare function traceSync<T>(name: string, fn: (span: Span) => T, options?: SpanOptions, tracer?: Tracer): T;
+/** Set key-value attributes on the currently active span. No-op when no span is recording. */
 export declare function addSpanAttributes(attributes: Record<string, string | number | boolean>): void;
+/** Add a named event to the currently active span. No-op when no span is recording. */
 export declare function addSpanEvent(name: string, attributes?: Record<string, string | number | boolean>): void;
+/** Get the currently active span from context, or `undefined`. */
 export declare function getActiveSpan(): Span | undefined;
+/** Execute a function with a specific span set as the active span in context. */
 export declare function withSpan<T>(span: Span, fn: () => T): T;
 export type { Span, SpanOptions, Tracer } from '@opentelemetry/api';
 export { context, propagation, trace } from './sdk';

package/dist/telemetry/tracing.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tracing.d.ts","sourceRoot":"","sources":["../../src/telemetry/tracing.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAW,KAAK,IAAI,EAAE,KAAK,WAAW,EAAE,KAAK,MAAM,EAAS,MAAM,oBAAoB,CAAC;AAG9F,wBAAsB,UAAU,CAAC,CAAC,EAC9B,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,EAC9B,OAAO,CAAC,EAAE,WAAW,EACrB,MAAM,CAAC,EAAE,MAAM,GAChB,OAAO,CAAC,CAAC,CAAC,CAYZ;AAED,wBAAgB,SAAS,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,CAAC,EAAE,OAAO,CAAC,EAAE,WAAW,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,CAAC,CAY3G;AAED,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,GAAG,IAAI,CAK7F;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,GAAG,IAAI,CAKvG;AAED,wBAAgB,aAAa,IAAI,IAAI,GAAG,SAAS,CAEhD;AAED,wBAAgB,QAAQ,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAEtD;AAED,YAAY,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AACpE,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,OAAO,CAAC"}
+{"version":3,"file":"tracing.d.ts","sourceRoot":"","sources":["../../src/telemetry/tracing.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAW,KAAK,IAAI,EAAE,KAAK,WAAW,EAAE,KAAK,MAAM,EAAS,MAAM,oBAAoB,CAAC;AAG9F;;;GAGG;AACH,wBAAsB,UAAU,CAAC,CAAC,EAC9B,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,EAC9B,OAAO,CAAC,EAAE,WAAW,EACrB,MAAM,CAAC,EAAE,MAAM,GAChB,OAAO,CAAC,CAAC,CAAC,CAYZ;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,CAAC,EAAE,OAAO,CAAC,EAAE,WAAW,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,CAAC,CAY3G;AAED,8FAA8F;AAC9F,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,GAAG,IAAI,CAK7F;AAED,uFAAuF;AACvF,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,GAAG,IAAI,CAKvG;AAED,kEAAkE;AAClE,wBAAgB,aAAa,IAAI,IAAI,GAAG,SAAS,CAEhD;AAED,iFAAiF;AACjF,wBAAgB,QAAQ,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAEtD;AAED,YAAY,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AACpE,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,OAAO,CAAC"}

package/dist/telemetry/tracing.js

@@ -3,6 +3,10 @@
  */
 import { context, trace } from '@opentelemetry/api';
 import { getTracer } from './sdk.js';
+/**
+ * Execute an async function within an active OTel span.
+ * The span is automatically ended and its status set on error.
+ */
 export async function traceAsync(name, fn, options, tracer) {
     const resolvedTracer = tracer ?? getTracer();
     return resolvedTracer.startActiveSpan(name, options ?? {}, async (span) => {
@@ -18,6 +22,10 @@ export async function traceAsync(name, fn, options, tracer) {
         }
     });
 }
+/**
+ * Execute a synchronous function within an active OTel span.
+ * The span is automatically ended and its status set on error.
+ */
 export function traceSync(name, fn, options, tracer) {
     const resolvedTracer = tracer ?? getTracer();
     return resolvedTracer.startActiveSpan(name, options ?? {}, (span) => {
@@ -33,21 +41,25 @@ export function traceSync(name, fn, options, tracer) {
         }
     });
 }
+/** Set key-value attributes on the currently active span. No-op when no span is recording. */
 export function addSpanAttributes(attributes) {
     const span = trace.getActiveSpan();
     if (span?.isRecording()) {
         span.setAttributes(attributes);
     }
 }
+/** Add a named event to the currently active span. No-op when no span is recording. */
 export function addSpanEvent(name, attributes) {
     const span = trace.getActiveSpan();
     if (span?.isRecording()) {
         span.addEvent(name, attributes);
     }
 }
+/** Get the currently active span from context, or `undefined`. */
 export function getActiveSpan() {
     return trace.getActiveSpan() ?? undefined;
 }
+/** Execute a function with a specific span set as the active span in context. */
 export function withSpan(span, fn) {
     return context.with(trace.setSpan(context.active(), span), fn);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gobing-ai/ts-infra",
-    "version": "0.3.0",
+    "version": "0.3.2",
     "description": "@gobing-ai/ts-infra — Infrastructure backbone: event bus, job queue, scheduler, telemetry, API client, and logging.",
     "keywords": [
         "typescript",
@@ -32,9 +32,21 @@
             "types": "./dist/index.d.ts",
             "import": "./dist/index.js"
         },
+        "./job-queue-db": {
+            "types": "./dist/job-queue-db.d.ts",
+            "import": "./dist/job-queue-db.js"
+        },
         "./otel-node": {
             "types": "./dist/telemetry/otel-node.d.ts",
             "import": "./dist/telemetry/otel-node.js"
+        },
+        "./scheduler-cloudflare": {
+            "types": "./dist/scheduler-cloudflare.d.ts",
+            "import": "./dist/scheduler-cloudflare.js"
+        },
+        "./scheduler-node": {
+            "types": "./dist/scheduler-node.d.ts",
+            "import": "./dist/scheduler-node.js"
         }
     },
     "files": [
@@ -54,9 +66,10 @@
         "release": "echo 'Manual publish is disabled. Releases go through GitHub Actions via Trusted Publishing — push a tag: git tag @gobing-ai/ts-infra-v<version> && git push --tags' && exit 1"
     },
     "dependencies": {
-        "@gobing-ai/ts-db": "^0.3.0"
+        "@logtape/logtape": "^2.0.0"
     },
     "peerDependencies": {
+        "@gobing-ai/ts-db": "^0.3.2",
         "@opentelemetry/api": "^1.9.0",
         "@opentelemetry/sdk-trace-node": "^2.0.0",
         "@opentelemetry/sdk-metrics": "^2.0.0",
@@ -66,6 +79,9 @@
         "@opentelemetry/exporter-metrics-otlp-http": ">=0.200.0"
     },
     "peerDependenciesMeta": {
+        "@gobing-ai/ts-db": {
+            "optional": true
+        },
         "@opentelemetry/sdk-trace-node": {
             "optional": true
         },
@@ -83,6 +99,7 @@
         }
     },
     "devDependencies": {
+        "@gobing-ai/ts-db": "^0.3.2",
         "@types/bun": "1.3.14",
         "@opentelemetry/api": "^1.9.0",
         "@opentelemetry/sdk-trace-node": "^2.0.0",

package/src/api-client.ts

@@ -16,6 +16,7 @@ import { traceAsync } from './telemetry/tracing';
 
 // ── Types ───────────────────────────────────────────────────────────
 
+/** Configuration for {@link APIClient}: base URL, default headers, timeout, and optional custom fetch. */
 export interface APIClientConfig {
     baseUrl: string;
     defaultHeaders?: Record<string, string>;
@@ -23,6 +24,7 @@ export interface APIClientConfig {
     fetch?: typeof globalThis.fetch;
 }
 
+/** Per-request overrides: headers, timeout, operation name, and abort signal. */
 export interface RequestOptions {
     headers?: Record<string, string>;
     timeout?: number;
@@ -30,6 +32,7 @@ export interface RequestOptions {
     signal?: AbortSignal;
 }
 
+/** HTTP error with status code and response body text. */
 export class APIError extends Error {
     constructor(
         public readonly status: number,
@@ -42,6 +45,16 @@ export class APIError extends Error {
 
 // ── Client ──────────────────────────────────────────────────────────
 
+/**
+ * Typed HTTP client builder wrapping fetch with automatic JSON serialization,
+ * timeout support, and OpenTelemetry tracing on every request.
+ *
+ * @example
+ * ```ts
+ * const client = new APIClient({ baseUrl: 'https://api.example.com' });
+ * const data = await client.get<User>('/users/1');
+ * ```
+ */
 export class APIClient {
     private readonly baseUrl: string;
     private readonly defaultHeaders: Record<string, string>;
@@ -97,8 +110,6 @@ export class APIClient {
                         signal: combinedSignal,
                     });
 
-                    if (timer) clearTimeout(timer);
-
                     span.setAttribute(ATTR_HTTP_RESPONSE_STATUS_CODE, response.status);
 
                     getHttpClientRequestTotal().add(1, {
@@ -128,8 +139,6 @@ export class APIClient {
 
                     return (await response.text()) as unknown as T;
                 } catch (error) {
-                    if (timer) clearTimeout(timer);
-
                     if (!(error instanceof APIError)) {
                         getHttpClientRequestErrors().add(1, {
                             'http.request.method': method,
@@ -138,6 +147,8 @@ export class APIClient {
                     }
 
                     throw error;
+                } finally {
+                    if (timer) clearTimeout(timer);
                 }
             },
             { kind: SpanKind.CLIENT },

package/src/event-bus/default-observers.ts

@@ -0,0 +1,117 @@
+/**
+ * Default lifecycle observers for EventBus self-observability.
+ *
+ * Connect `BusLifecycleEvents` to the logging and telemetry infrastructure so
+ * operators get visibility without wiring everything by hand. Opt-in: nothing
+ * is attached unless you call one of these.
+ *
+ * **Metrics are intentionally omitted here.** Unlike the original design, the
+ * `EventBus` core now increments `eventbus.emits.total` / `eventbus.errors.total`
+ * inline on every emit (see `event-bus.ts`). A metrics observer would
+ * double-count, so the restored default set is **log + telemetry-trace only**.
+ *
+ * @example One-liner setup
+ * ```ts
+ * import { EventBus, createLifecycleBus, attachDefaultObservers } from '@gobing-ai/ts-infra';
+ *
+ * const lifecycleBus = createLifecycleBus();
+ * attachDefaultObservers(lifecycleBus);
+ *
+ * const appBus = new EventBus<AppEvents>({ lifecycleBus });
+ * ```
+ */
+
+import { getLogger, type Logger } from '../logger';
+import { addSpanAttributes, addSpanEvent, traceAsync } from '../telemetry/tracing';
+import { EventBus } from './event-bus';
+import type { BusLifecycleEvents } from './types';
+
+let _obsLogger: Logger | undefined;
+function obsLogger(): Logger {
+    if (!_obsLogger) _obsLogger = getLogger('event-bus.observers');
+    return _obsLogger;
+}
+
+/**
+ * Create a dedicated `EventBus<BusLifecycleEvents>` for use as the
+ * `lifecycleBus` constructor argument on another `EventBus`.
+ */
+export function createLifecycleBus(): EventBus<BusLifecycleEvents> {
+    return new EventBus<BusLifecycleEvents>();
+}
+
+/**
+ * Register handlers that write structured log entries for every lifecycle event.
+ *
+ * - `bus.emit.done`   → debug (warn if errors > 0)
+ * - `bus.emit.noop`   → debug
+ * - `bus.handler.error` → warn
+ * - `bus.handler.async.enqueued` → debug
+ */
+export function attachLogObserver(lifecycleBus: EventBus<BusLifecycleEvents>): void {
+    lifecycleBus.on('bus.emit.done', (detail) => {
+        if (detail.errors > 0) {
+            obsLogger().warn('emit completed with errors', { ...detail });
+        } else {
+            obsLogger().debug('emit done', { ...detail });
+        }
+    });
+
+    lifecycleBus.on('bus.emit.noop', (detail) => {
+        obsLogger().debug('emit with zero handlers', { ...detail });
+    });
+
+    lifecycleBus.on('bus.handler.error', (detail) => {
+        obsLogger().warn('handler error', { ...detail });
+    });
+
+    lifecycleBus.on('bus.handler.async.enqueued', (detail) => {
+        obsLogger().debug('async job enqueued', { ...detail });
+    });
+}
+
+/**
+ * Register handlers that create OpenTelemetry spans for emit operations.
+ *
+ * Each `bus.emit.done` creates a span named `eventbus.emit.{EVENT}` with
+ * attributes for sync/async counts, duration, and error count. Degrades
+ * gracefully when telemetry is not initialised (`traceAsync` is a pass-through).
+ */
+export function attachTelemetryObserver(lifecycleBus: EventBus<BusLifecycleEvents>): void {
+    lifecycleBus.on('bus.emit.done', (detail) => {
+        void traceAsync(`eventbus.emit.${detail.event}`, async (_span) => {
+            addSpanAttributes({
+                'eventbus.event': detail.event,
+                'eventbus.sync_count': detail.syncCount,
+                'eventbus.async_count': detail.asyncCount,
+                'eventbus.duration_ms': detail.emitDurationMs,
+                'eventbus.errors': detail.errors,
+            });
+
+            if (detail.errors > 0) {
+                addSpanEvent('eventbus.emit.errors', { 'eventbus.error_count': detail.errors });
+            }
+        });
+    });
+
+    lifecycleBus.on('bus.handler.error', (detail) => {
+        void traceAsync('eventbus.handler.error', async (span) => {
+            addSpanAttributes({
+                'eventbus.event': detail.event,
+                'eventbus.handler_mode': detail.mode,
+                'eventbus.error': detail.error,
+            });
+            span.setStatus({ code: 2, message: detail.error }); // ERROR
+        });
+    });
+}
+
+/**
+ * Attach the built-in observers (log + telemetry) to the lifecycle bus in one
+ * call. Recommended default for production deployments. Metrics are emitted by
+ * the `EventBus` core inline, so they are not part of this set.
+ */
+export function attachDefaultObservers(lifecycleBus: EventBus<BusLifecycleEvents>): void {
+    attachLogObserver(lifecycleBus);
+    attachTelemetryObserver(lifecycleBus);
+}

package/src/event-bus/event-bus.ts

@@ -118,6 +118,7 @@ export class EventBus<TEvents extends EventMap> {
                         });
                         busLogger().debug('async job enqueued', { event: eventName, jobId, handlerCount: 1 });
                         this.publishAsyncEnqueued(eventName, jobId, 1);
+                        continue;
                     } catch (error) {
                         errors++;
                         const message = error instanceof Error ? error.message : String(error);

package/src/event-bus/file-observer.ts

@@ -0,0 +1,142 @@
+import { getLogger } from '../logger';
+import type { EventBus } from './event-bus';
+import type { BusLifecycleEvents } from './types';
+
+/**
+ * Minimal append-only file writer the file observer needs.
+ *
+ * ADR-011: ts-infra must not import `node:fs`. The caller injects a writer —
+ * typically `@gobing-ai/ts-runtime`'s `FileSystem`, which already satisfies
+ * this shape (`ensureDir` + `appendFile`).
+ */
+export interface FileObserverWriter {
+    /** Ensure the directory exists. Called once with the parent dir of the file. */
+    ensureDir(dir: string): void | Promise<void>;
+    /** Append `content` to `path`, creating the file if absent. */
+    appendFile(path: string, content: string): void | Promise<void>;
+}
+
+/** Parent directory of a `/`-separated path (no `node:path` dependency). */
+function parentDir(filePath: string): string {
+    const idx = filePath.lastIndexOf('/');
+    return idx <= 0 ? '.' : filePath.slice(0, idx);
+}
+
+function isPromiseLike(value: unknown): value is PromiseLike<unknown> {
+    return value !== null && typeof value === 'object' && 'then' in value;
+}
+
+/**
+ * Register handlers on `lifecycleBus` that append structured JSON lines to
+ * `filePath` for every lifecycle event.
+ *
+ * @param lifecycleBus - The bus to observe.
+ * @param filePath - Path to the JSONL output file.
+ * @param writer - Injected file writer (e.g. ts-runtime `FileSystem`).
+ */
+export function attachFileObserver(
+    lifecycleBus: EventBus<BusLifecycleEvents>,
+    filePath: string,
+    writer: FileObserverWriter,
+): void {
+    const logger = getLogger('event-bus.file-observer');
+    const ensureResult = writer.ensureDir(parentDir(filePath));
+    let ready = !isPromiseLike(ensureResult);
+    let pending = isPromiseLike(ensureResult);
+    let setupFailed = false;
+    let sequence = 0;
+    let writeChain: Promise<unknown> = isPromiseLike(ensureResult)
+        ? Promise.resolve(ensureResult)
+              .then(() => {
+                  ready = true;
+              })
+              .catch((error) => {
+                  setupFailed = true;
+                  logger.warn('failed to prepare event bus file observer directory', {
+                      filePath,
+                      error: error instanceof Error ? error.message : String(error),
+                  });
+              })
+        : Promise.resolve();
+
+    function setPending(next: Promise<unknown>): void {
+        const current = ++sequence;
+        pending = true;
+        writeChain = next
+            .catch((error) => {
+                logger.warn('failed to append event bus lifecycle event', {
+                    filePath,
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            })
+            .finally(() => {
+                if (sequence === current) pending = false;
+            });
+    }
+
+    function writeLine(line: Record<string, unknown>): void {
+        const content = `${JSON.stringify(line)}\n`;
+        if (setupFailed) return;
+
+        if (ready && !pending) {
+            const result = writer.appendFile(filePath, content);
+            if (isPromiseLike(result)) {
+                setPending(Promise.resolve(result));
+            }
+            return;
+        }
+
+        setPending(
+            writeChain.then(() => {
+                if (setupFailed) return;
+                return writer.appendFile(filePath, content);
+            }),
+        );
+    }
+
+    lifecycleBus.on('bus.emit.done', (d) => {
+        const payload =
+            d.detail !== null && typeof d.detail === 'object' && !Array.isArray(d.detail)
+                ? (d.detail as Record<string, unknown>)
+                : undefined;
+
+        writeLine({
+            ts: new Date().toISOString(),
+            lifecycle: 'bus.emit.done',
+            event: d.event,
+            syncCount: d.syncCount,
+            asyncCount: d.asyncCount,
+            emitDurationMs: d.emitDurationMs,
+            errors: d.errors,
+            ...(payload && Object.keys(payload).length > 0 ? { payload } : {}),
+        });
+    });
+
+    lifecycleBus.on('bus.emit.noop', (d) => {
+        writeLine({
+            ts: new Date().toISOString(),
+            lifecycle: 'bus.emit.noop',
+            event: d.event,
+        });
+    });
+
+    lifecycleBus.on('bus.handler.error', (d) => {
+        writeLine({
+            ts: new Date().toISOString(),
+            lifecycle: 'bus.handler.error',
+            event: d.event,
+            mode: d.mode,
+            error: d.error,
+        });
+    });
+
+    lifecycleBus.on('bus.handler.async.enqueued', (d) => {
+        writeLine({
+            ts: new Date().toISOString(),
+            lifecycle: 'bus.handler.async.enqueued',
+            event: d.event,
+            jobId: d.jobId,
+            handlerCount: d.handlerCount,
+        });
+    });
+}