@gobing-ai/ts-infra 0.3.1 → 0.3.3

package/src/event-bus/index.ts

@@ -1,4 +1,11 @@
+export {
+    attachDefaultObservers,
+    attachLogObserver,
+    attachTelemetryObserver,
+    createLifecycleBus,
+} from './default-observers';
 export { EventBus } from './event-bus';
+export { attachFileObserver, type FileObserverWriter } from './file-observer';
 export type {
     AsyncEnqueuedDetail,
     BusLifecycleEvents,

package/src/event-bus/types.ts

@@ -2,8 +2,10 @@
  * Event bus types — shared constraints for typed pub-sub.
  */
 
+/** Type constraint for event maps — keys are event names, values are listener signatures. */
 export type EventMap = Record<string, (...args: never[]) => void>;
 
+/** Options for subscribing to an event, including async dispatch mode. */
 export interface SubscribeOptions {
     /** When true, the handler is dispatched through the async handler path. */
     async?: boolean;
@@ -11,6 +13,7 @@ export interface SubscribeOptions {
 
 // ── Lifecycle events ────────────────────────────────────────────────
 
+/** Payload emitted on `bus.emit.done` after synchronous handlers complete. */
 export interface EmitDoneDetail {
     event: string;
     syncCount: number;
@@ -20,18 +23,21 @@ export interface EmitDoneDetail {
     detail?: unknown;
 }
 
+/** Payload emitted on `bus.handler.error` when a handler throws. */
 export interface HandlerErrorDetail {
     event: string;
     mode: 'sync' | 'async';
     error: string;
 }
 
+/** Payload emitted on `bus.handler.async.enqueued` when async handlers are scheduled. */
 export interface AsyncEnqueuedDetail {
     event: string;
     jobId: string;
     handlerCount: number;
 }
 
+/** Strongly-typed lifecycle events emitted by the event bus. */
 export type BusLifecycleEvents = {
     'bus.emit.done': (detail: EmitDoneDetail) => void;
     'bus.emit.noop': (detail: { event: string }) => void;

package/src/events.ts

@@ -0,0 +1,108 @@
+/**
+ * Infrastructure-level event definitions for ts-infra observability.
+ *
+ * Mirrors the package-local pattern in `@gobing-ai/ts-ai-runner` (`events.ts`):
+ * only the events ts-infra components actually emit live here. Application-domain
+ * events (history import, HTTP server, …) belong to the consuming app, not this
+ * library. Process events belong to `@gobing-ai/ts-runtime` (the owner of
+ * `ProcessExecutor`) and are intentionally not re-exported here.
+ *
+ * Consume via `EventBus<InfraEvents>` or compose individual maps into a wider
+ * app event map.
+ */
+
+import type { QueueStats } from './job-queue/types';
+
+// ── Detail payloads ────────────────────────────────────────────────────────
+
+/** Payload for `db.connection.error`. */
+export interface DbConnectionErrorDetail {
+    /** Error message. */
+    error: string;
+    /** Adapter type (e.g. 'sqlite', 'd1'). */
+    adapter: string;
+}
+
+/** Payload for `queue.job.failed` — a job exhausted retries. */
+export interface QueueJobFailedDetail {
+    jobId: string;
+    type: string;
+    error: string;
+    /** Attempt number (0-indexed, incremented after each failure). */
+    attempt: number;
+}
+
+/** Payload for `queue.job.retrying` — a job will be retried after backoff. */
+export interface QueueJobRetryingDetail {
+    jobId: string;
+    type: string;
+    attempt: number;
+    /** When the next retry will fire (epoch ms). */
+    nextRetryAt: number;
+}
+
+/** Payload for `scheduler.job.executed`. */
+export interface SchedulerJobExecutedDetail {
+    /** Job name. */
+    name: string;
+    /** Wall-clock duration in milliseconds. */
+    durationMs: number;
+    /** Error message if the job threw. */
+    error?: string;
+}
+
+/** Payload for `api.request.error`. */
+export interface ApiRequestErrorDetail {
+    url: string;
+    method: string;
+    /** HTTP status code, if a response was received. */
+    status?: number;
+    error: string;
+}
+
+// ── Event maps ─────────────────────────────────────────────────────────────
+
+/** Database lifecycle events emitted by DB-facing infra wiring. */
+export type DbEvents = {
+    /** Database connection established. */
+    'db.connected': () => void;
+    /** Database connection error. */
+    'db.connection.error': (detail: DbConnectionErrorDetail) => void;
+};
+
+/** Job-queue lifecycle events emitted by the queue and its consumer. */
+export type QueueEvents = {
+    /** A new job was enqueued. */
+    'queue.job.enqueued': (detail: { jobId: string; type: string }) => void;
+    /** Consumer polling loop started. */
+    'queue.consumer.started': () => void;
+    /** Consumer stopped. */
+    'queue.consumer.stopped': () => void;
+    /** A job completed successfully. */
+    'queue.job.completed': (detail: { jobId: string; type: string }) => void;
+    /** A job exhausted retries and is permanently failed. */
+    'queue.job.failed': (detail: QueueJobFailedDetail) => void;
+    /** A job will be retried after backoff. */
+    'queue.job.retrying': (detail: QueueJobRetryingDetail) => void;
+    /** Queue depth snapshot emitted on a poll cycle. */
+    'queue.stats': (detail: QueueStats) => void;
+};
+
+/** Scheduler events emitted by scheduler adapters and the handler wrapper. */
+export type SchedulerEvents = {
+    /** A scheduled job was executed (success or failure). */
+    'scheduler.job.executed': (detail: SchedulerJobExecutedDetail) => void;
+};
+
+/** API-client events. */
+export type ApiClientEvents = {
+    /** An API request failed (non-2xx or network error). */
+    'api.request.error': (detail: ApiRequestErrorDetail) => void;
+};
+
+/**
+ * Aggregate of all infrastructure-level event maps ts-infra emits. Use with
+ * `EventBus<InfraEvents>`, or pick individual maps when composing a wider app
+ * event map.
+ */
+export type InfraEvents = DbEvents & QueueEvents & SchedulerEvents & ApiClientEvents;

package/src/index.ts

@@ -2,7 +2,31 @@
 export { APIClient, type APIClientConfig, APIError, type RequestOptions } from './api-client';
 
 // Event Bus
-export { EventBus, type EventMap, type SubscribeOptions } from './event-bus/index';
+export {
+    attachDefaultObservers,
+    attachFileObserver,
+    attachLogObserver,
+    attachTelemetryObserver,
+    createLifecycleBus,
+    EventBus,
+    type EventMap,
+    type FileObserverWriter,
+    type SubscribeOptions,
+} from './event-bus/index';
+
+// Events (infrastructure-level event maps)
+export type {
+    ApiClientEvents,
+    ApiRequestErrorDetail,
+    DbConnectionErrorDetail,
+    DbEvents,
+    InfraEvents,
+    QueueEvents,
+    QueueJobFailedDetail,
+    QueueJobRetryingDetail,
+    SchedulerEvents,
+    SchedulerJobExecutedDetail,
+} from './events';
 
 export type {
     EnqueueOptions,
@@ -13,22 +37,35 @@ export type {
     QueueConsumerConfig,
     QueueStats,
 } from './job-queue/index';
-// Job Queue
-export { DBJobQueue, DBQueueConsumer } from './job-queue/index';
-
 // Logger
-export { getLogger, initializeLogger, type Logger, type LogLevel } from './logger';
+export {
+    getLogger,
+    type InitLoggerOptions,
+    initializeLogger,
+    type Logger,
+    type LogLevel,
+    setLoggerMuted,
+} from './logger';
 
 // Scheduler
 export {
-    CloudflareSchedulerAdapter,
+    ActionRegistry,
+    type CreateDefaultRegistryOptions,
+    createDefaultRegistry,
     getSchedulerAdapter,
+    HealthPingAction,
+    type HealthPingWriter,
     initScheduler,
-    NodeSchedulerAdapter,
+    LogAction,
     NoopSchedulerAdapter,
+    QueueStatsAction,
+    type QueueStatsDaoProvider,
     type ScheduledAction,
+    type SchedulerAction,
     type SchedulerAdapter,
     setSchedulerAdapter,
+    toScheduledAction,
+    wrapScheduledHandler,
 } from './scheduler/index';
 
 // Telemetry

package/src/job-queue/db-job-queue.ts

@@ -5,6 +5,7 @@ import {
     getQueueJobFailedTotal,
     getQueueJobProcessingDuration,
 } from '../telemetry/metrics';
+import { addSpanAttributes, traceAsync } from '../telemetry/tracing';
 import type { EnqueueOptions, Job, JobHandler, JobQueue, QueueConsumer, QueueConsumerConfig } from './types';
 
 /** DB-backed job queue implementation over `@gobing-ai/ts-db`'s `QueueJobDao`. */
@@ -84,28 +85,31 @@ export class DBQueueConsumer<T = unknown> implements QueueConsumer<T> {
 
     /** Process one batch immediately. Useful for tests, schedulers, and manual drains. */
     async processOnce(): Promise<number> {
-        await this.dao.resetStuckJobs(this.visibilityTimeout);
-        await this.dao.failExpiredJobs();
-
-        const jobs = await this.dao.claimReady(this.batchSize);
-        let processed = 0;
-
-        for (let index = 0; index < jobs.length; index += this.maxConcurrency) {
-            const batch = jobs.slice(index, index + this.maxConcurrency);
-            await Promise.all(
-                batch.map(async (job) => {
-                    this.inFlight += 1;
-                    try {
-                        await this.processJob(job);
-                        processed += 1;
-                    } finally {
-                        this.inFlight -= 1;
-                    }
-                }),
-            );
-        }
-
-        return processed;
+        return traceAsync('queue.poll', async () => {
+            await this.dao.resetStuckJobs(this.visibilityTimeout);
+            await this.dao.failExpiredJobs();
+
+            const jobs = await this.dao.claimReady(this.batchSize);
+            let processed = 0;
+
+            for (let index = 0; index < jobs.length; index += this.maxConcurrency) {
+                const batch = jobs.slice(index, index + this.maxConcurrency);
+                await Promise.all(
+                    batch.map(async (job) => {
+                        this.inFlight += 1;
+                        try {
+                            await this.processJob(job);
+                            processed += 1;
+                        } finally {
+                            this.inFlight -= 1;
+                        }
+                    }),
+                );
+            }
+
+            addSpanAttributes({ 'queue.claimed': jobs.length, 'queue.processed': processed });
+            return processed;
+        });
     }
 
     private schedule(delay: number): void {
@@ -125,22 +129,30 @@ export class DBQueueConsumer<T = unknown> implements QueueConsumer<T> {
 
     private async processJob(record: QueueJobRecord): Promise<void> {
         const job = toJob<T>(record);
-        const handler = this.handlers.get(job.type);
-        if (handler === undefined) {
-            await this.failOrRetry(job, new Error(`No handler registered for job type "${job.type}"`));
-            return;
-        }
-
-        const startMs = performance.now();
-        try {
-            await handler(job);
-            await this.dao.markCompleted(job.id);
-            getQueueJobCompletedTotal().add(1, { type: job.type });
-            getQueueJobProcessingDuration().record(performance.now() - startMs, { type: job.type });
-        } catch (error) {
-            getQueueJobProcessingDuration().record(performance.now() - startMs, { type: job.type });
-            await this.failOrRetry(job, error);
-        }
+        return traceAsync('queue.job.process', async () => {
+            addSpanAttributes({
+                'queue.job_id': job.id,
+                'queue.job_type': job.type,
+                'queue.job_attempt': job.attempts,
+            });
+
+            const handler = this.handlers.get(job.type);
+            if (handler === undefined) {
+                await this.failOrRetry(job, new Error(`No handler registered for job type "${job.type}"`));
+                return;
+            }
+
+            const startMs = performance.now();
+            try {
+                await handler(job);
+                await this.dao.markCompleted(job.id);
+                getQueueJobCompletedTotal().add(1, { type: job.type });
+                getQueueJobProcessingDuration().record(performance.now() - startMs, { type: job.type });
+            } catch (error) {
+                getQueueJobProcessingDuration().record(performance.now() - startMs, { type: job.type });
+                await this.failOrRetry(job, error);
+            }
+        });
     }
 
     private async failOrRetry(job: Job<T>, error: unknown): Promise<void> {

package/src/job-queue/index.ts

@@ -1,4 +1,3 @@
-export { DBJobQueue, DBQueueConsumer } from './db-job-queue';
 export type {
     EnqueueOptions,
     Job,

package/src/job-queue/types.ts

@@ -5,6 +5,7 @@
  * `DBJobQueue` and `DBQueueConsumer`.
  */
 
+/** A queued job with status tracking, retry metadata, and timestamps. */
 export interface Job<T = unknown> {
     id: string;
     type: string;
@@ -19,20 +20,24 @@ export interface Job<T = unknown> {
     processingAt: number | null;
 }
 
+/** Options for enqueuing a job: retry policy, delay, and TTL. */
 export interface EnqueueOptions {
     maxRetries?: number;
     delay?: number;
     ttlMs?: number;
 }
 
+/** Producer interface for the job queue — enqueue single jobs or batches. */
 export interface JobQueue<T = unknown> {
     enqueue(type: string, payload: T, options?: EnqueueOptions): Promise<string>;
     enqueueBatch(jobs: Array<{ type: string; payload: T } & EnqueueOptions>): Promise<string[]>;
     stats(): Promise<QueueStats>;
 }
 
+/** Async handler that processes a single job. */
 export type JobHandler<T = unknown> = (job: Job<T>) => Promise<void>;
 
+/** Aggregate statistics for a job queue: counts by status. */
 export interface QueueStats {
     pending: number;
     processing: number;
@@ -40,6 +45,7 @@ export interface QueueStats {
     failed: number;
 }
 
+/** Configuration for a queue consumer: polling, concurrency, and backoff. */
 export interface QueueConsumerConfig {
     pollInterval?: number;
     batchSize?: number;
@@ -50,6 +56,7 @@ export interface QueueConsumerConfig {
     drainTimeoutMs?: number;
 }
 
+/** Consumer interface for the job queue — register handlers and control the processing loop. */
 export interface QueueConsumer<T = unknown> {
     register(type: string, handler: JobHandler<T>): void;
     start(): Promise<void>;

package/src/job-queue-db.ts

@@ -0,0 +1 @@
+export { DBJobQueue, DBQueueConsumer } from './job-queue/db-job-queue';

package/src/logger.ts

@@ -1,20 +1,45 @@
 /**
- * Structured JSON logger with levels (trace/debug/info/warn/error/fatal).
+ * Structured logger for ts-infra, backed by LogTape.
  *
- * No external dependencies — console-based implementation.
+ * LogTape owns level filtering, sink routing, and formatting; this module
+ * adapts LogTape's template-string logger to the ts-infra `Logger` contract
+ * (`method(msg, data?)` + `child(context)`) so call-sites stay backend-agnostic.
+ *
+ * ADR-011: ts-infra must not touch `node:fs`/`process.stderr`. The console sink
+ * is LogTape's own (`getConsoleSink`); the file sink is supplied by the caller
+ * (typically `@gobing-ai/ts-runtime`, which owns FileSystem) via
+ * {@link InitLoggerOptions.fileSink}.
  */
 
+import {
+    ConfigError,
+    configure,
+    getConsoleSink,
+    getJsonLinesFormatter,
+    getTextFormatter,
+    type LogRecord,
+    type Logger as LtLogger,
+    getLogger as ltGetLogger,
+    reset,
+    type Sink,
+} from '@logtape/logtape';
+
+/** Log severity levels in ascending order: trace → debug → info → warn → error → fatal. */
 export type LogLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal';
 
-const LEVEL_ORDER: Record<LogLevel, number> = {
-    trace: 0,
-    debug: 1,
-    info: 2,
-    warn: 3,
-    error: 4,
-    fatal: 5,
-};
+/** Root category every ts-infra logger lives under, so one config rule covers them all. */
+const ROOT_CATEGORY = 'app';
+
+/** Map the ts-infra level name to LogTape's (`warn` → `warning`). */
+function toLogTapeLevel(level: LogLevel): 'trace' | 'debug' | 'info' | 'warning' | 'error' | 'fatal' {
+    return level === 'warn' ? 'warning' : level;
+}
 
+/**
+ * Structured logger interface with level methods and context inheritance
+ * via {@link Logger.child}. `data` is attached as structured properties —
+ * `msg` is logged verbatim (no template substitution).
+ */
 export interface Logger {
     trace(msg: string, data?: Record<string, unknown>): void;
     debug(msg: string, data?: Record<string, unknown>): void;
@@ -25,99 +50,99 @@ export interface Logger {
     child(context: Record<string, unknown>): Logger;
 }
 
-class ConsoleLogger implements Logger {
-    private readonly context: Record<string, unknown>;
-
-    constructor(
-        private readonly category: string,
-        context: Record<string, unknown> = {},
-    ) {
-        this.context = { category, ...context };
-    }
+/** Module-level mute flag — LogTape has no global mute, so the adapter gates on it. */
+let muted = false;
 
-    private log(level: LogLevel, msg: string, data?: Record<string, unknown>): void {
-        // Read the level dynamically so re-initialization affects cached loggers too.
-        if (LEVEL_ORDER[level] < LEVEL_ORDER[globalLevel]) return;
-        if (globalMuted) return;
-
-        const entry = {
-            level,
-            message: msg,
-            timestamp: new Date().toISOString(),
-            ...this.context,
-            ...data,
-        };
+/**
+ * Mute or unmute all logger output. Useful for tests. Gating happens in the
+ * adapter before delegating to LogTape, so muting is synchronous and global.
+ */
+export function setLoggerMuted(value: boolean): void {
+    muted = value;
+}
 
-        const json = JSON.stringify(entry);
-        switch (level) {
-            case 'error':
-            case 'fatal':
-                console.error(json);
-                break;
-            case 'warn':
-                console.warn(json);
-                break;
-            case 'debug':
-            case 'trace':
-                console.debug(json);
-                break;
-            default:
-                console.log(json);
-        }
-    }
+/** Adapter: ts-infra `Logger` over a LogTape logger. */
+class LogTapeLogger implements Logger {
+    constructor(private readonly inner: LtLogger) {}
 
     trace(msg: string, data?: Record<string, unknown>): void {
-        this.log('trace', msg, data);
+        if (!muted) this.inner.trace(msg, data ?? {});
     }
     debug(msg: string, data?: Record<string, unknown>): void {
-        this.log('debug', msg, data);
+        if (!muted) this.inner.debug(msg, data ?? {});
     }
     info(msg: string, data?: Record<string, unknown>): void {
-        this.log('info', msg, data);
+        if (!muted) this.inner.info(msg, data ?? {});
     }
     warn(msg: string, data?: Record<string, unknown>): void {
-        this.log('warn', msg, data);
+        if (!muted) this.inner.warn(msg, data ?? {});
     }
     error(msg: string, data?: Record<string, unknown>): void {
-        this.log('error', msg, data);
+        if (!muted) this.inner.error(msg, data ?? {});
     }
     fatal(msg: string, data?: Record<string, unknown>): void {
-        this.log('fatal', msg, data);
+        if (!muted) this.inner.fatal(msg, data ?? {});
     }
 
     child(context: Record<string, unknown>): Logger {
-        return new ConsoleLogger(this.category, { ...this.context, ...context });
+        return new LogTapeLogger(this.inner.with(context));
     }
 }
 
-const loggers = new Map<string, ConsoleLogger>();
-
-let globalLevel: LogLevel = 'info';
-let globalMuted = false;
-
-/**
- * Mute or unmute all logger console output. Useful for tests.
- */
-export function setLoggerMuted(muted: boolean): void {
-    globalMuted = muted;
-}
-
 /**
- * Get or create a logger for the given category.
+ * Get a logger for the given category. Categories are nested under the
+ * `app` root so a single `initializeLogger` rule configures them all.
  */
 export function getLogger(category: string): Logger {
-    const existing = loggers.get(category);
-    if (existing) return existing;
+    return new LogTapeLogger(ltGetLogger([ROOT_CATEGORY, category]));
+}
 
-    const logger = new ConsoleLogger(category);
-    loggers.set(category, logger);
-    return logger;
+/** Options for {@link initializeLogger}. */
+export interface InitLoggerOptions {
+    /** Minimum level to emit. Default `info`. */
+    level?: LogLevel;
+    /** Enable the console sink. Default `true`. */
+    console?: boolean;
+    /**
+     * File sink writer. ts-infra never opens files itself (ADR-011); the
+     * caller (e.g. ts-runtime FileSystem) provides a writer that appends one
+     * already-formatted line per record. When omitted, no file sink is wired.
+     */
+    fileSink?: (line: string) => void;
+    /** Format records as JSON Lines (`true`) or human-readable text (`false`). Default `true`. */
+    json?: boolean;
 }
 
 /**
- * Initialize the logger subsystem with a minimum log level.
+ * Configure LogTape with console and/or file sinks. Call once at startup;
+ * safe to call again to reconfigure — the prior config is reset first so the
+ * latest call wins (LogTape throws `ConfigError` on double-configure otherwise).
  */
-export function initializeLogger(level: LogLevel = 'info'): void {
-    globalLevel = level;
-    loggers.clear();
+export async function initializeLogger(options: InitLoggerOptions = {}): Promise<void> {
+    const { level = 'info', console: enableConsole = true, fileSink, json = true } = options;
+    const lowestLevel = toLogTapeLevel(level);
+    const formatter = json ? getJsonLinesFormatter() : getTextFormatter();
+
+    const sinks: Record<string, Sink> = {};
+    if (enableConsole) {
+        sinks.console = getConsoleSink({ formatter });
+    }
+    if (fileSink) {
+        sinks.file = (record: LogRecord) => {
+            fileSink(formatter(record));
+        };
+    }
+
+    await reset();
+    try {
+        await configure({
+            sinks,
+            loggers: [
+                { category: [ROOT_CATEGORY], lowestLevel, sinks: Object.keys(sinks) },
+                { category: ['logtape', 'meta'], lowestLevel: 'warning', sinks: [] },
+            ],
+        });
+    } catch (error) {
+        if (!(error instanceof ConfigError)) throw error;
+    }
 }