@gobing-ai/ts-infra 0.3.0 → 0.3.2

package/src/scheduler/action.ts

@@ -1,4 +1,167 @@
 /**
- * Scheduler action type re-export.
+ * Named scheduler actions and a registry, plus built-in actions.
+ *
+ * Opt-in by design: `createDefaultRegistry` only auto-registers the side-effect-
+ * free `LogAction`. Actions with side effects (`QueueStatsAction` needs a DAO
+ * provider, `HealthPingAction` needs a file writer) are included only when their
+ * dependency is supplied — downstream code decides what to enable.
  */
+
+import type { EventBus } from '../event-bus/event-bus';
+import type { QueueEvents } from '../events';
+import type { QueueStats } from '../job-queue/types';
+import { getLogger } from '../logger';
+import type { ScheduledAction } from './types';
+
+const logger = getLogger('scheduler.action');
+
+/** Lazily provides a DAO with `getStats()`, deferred to execution time. */
+export type QueueStatsDaoProvider = () => Promise<{ getStats(): Promise<QueueStats> }>;
+
+/**
+ * Minimal writer for {@link HealthPingAction}. ADR-011: ts-infra does not touch
+ * `node:fs`; the caller injects a writer (e.g. ts-runtime `FileSystem`).
+ */
+export interface HealthPingWriter {
+    /** Write `content` to `path`, replacing any existing file. */
+    writeFile(path: string, content: string): void | Promise<void>;
+}
+
+/**
+ * A named action invokable by the scheduler. Registered in an
+ * {@link ActionRegistry} and resolved by name; `execute()` matches the
+ * adapter's no-arg {@link ScheduledAction} signature.
+ */
+export interface SchedulerAction {
+    /** Unique action name registered in the registry. */
+    readonly name: string;
+    /** Execute the action. */
+    execute(): Promise<void>;
+}
+
+/** Bridge a {@link SchedulerAction} to a plain {@link ScheduledAction} for adapter registration. */
+export function toScheduledAction(action: SchedulerAction): ScheduledAction {
+    return () => action.execute();
+}
+
+/**
+ * Registry of named {@link SchedulerAction} instances, resolved at scheduler
+ * startup. Duplicate names are rejected.
+ */
+export class ActionRegistry {
+    private readonly map = new Map<string, SchedulerAction>();
+
+    constructor(actions?: SchedulerAction[]) {
+        if (actions) {
+            for (const action of actions) this.register(action);
+        }
+    }
+
+    /** Register an action. @throws if the name is already registered. */
+    register(action: SchedulerAction): void {
+        if (this.map.has(action.name)) {
+            throw new Error(`Duplicate scheduler action name: "${action.name}"`);
+        }
+        this.map.set(action.name, action);
+    }
+
+    /** Look up an action by name. */
+    get(name: string): SchedulerAction | undefined {
+        return this.map.get(name);
+    }
+
+    /** Whether an action with the given name exists. */
+    has(name: string): boolean {
+        return this.map.has(name);
+    }
+
+    /** All registered action names. */
+    names(): string[] {
+        return [...this.map.keys()];
+    }
+}
+
+/** Logs a structured info message on every invocation. Registered as `"log"`. */
+export class LogAction implements SchedulerAction {
+    readonly name: string;
+
+    constructor(name = 'log') {
+        this.name = name;
+    }
+
+    async execute(): Promise<void> {
+        logger.info('Scheduled action executed', { action: this.name });
+    }
+}
+
+/**
+ * Queries the queue DAO for stats and logs them; emits `queue.stats` when a
+ * system bus is provided. Registered as `"queue-stats"`.
+ */
+export class QueueStatsAction implements SchedulerAction {
+    readonly name = 'queue-stats';
+
+    constructor(
+        private readonly daoProvider: QueueStatsDaoProvider,
+        private readonly systemBus: EventBus<QueueEvents> | null = null,
+    ) {}
+
+    async execute(): Promise<void> {
+        const dao = await this.daoProvider();
+        const stats = await dao.getStats();
+        logger.info('Queue stats snapshot', { action: this.name, ...stats });
+        this.systemBus?.emit('queue.stats', stats);
+    }
+}
+
+/**
+ * Writes a timestamped heartbeat file on every invocation. Registered as
+ * `"health-ping"`. File I/O is delegated to an injected {@link HealthPingWriter}.
+ */
+export class HealthPingAction implements SchedulerAction {
+    readonly name = 'health-ping';
+
+    constructor(
+        private readonly writer: HealthPingWriter,
+        private readonly filePath = 'data/scheduler-heartbeat.json',
+    ) {}
+
+    async execute(): Promise<void> {
+        const content = JSON.stringify({
+            lastRun: new Date().toISOString(),
+            jobName: this.name,
+        });
+        await this.writer.writeFile(this.filePath, content);
+    }
+}
+
+/** Options for {@link createDefaultRegistry}. */
+export interface CreateDefaultRegistryOptions {
+    /** DAO provider for `QueueStatsAction`. Omit to exclude that action. */
+    queueStatsDaoProvider?: QueueStatsDaoProvider;
+    /** Writer for `HealthPingAction`. Omit to exclude that action. */
+    healthPingWriter?: HealthPingWriter;
+    /** File path for `HealthPingAction`. Default `"data/scheduler-heartbeat.json"`. */
+    healthPingPath?: string;
+    /** System bus forwarded to `QueueStatsAction` for `queue.stats` events. */
+    systemBus?: EventBus<QueueEvents> | null;
+}
+
+/**
+ * Create an {@link ActionRegistry} with the built-in actions. Only `LogAction`
+ * is always present (no side effects); `QueueStatsAction` and `HealthPingAction`
+ * are included only when their dependency (`queueStatsDaoProvider` /
+ * `healthPingWriter`) is supplied — so nothing with side effects is auto-wired.
+ */
+export function createDefaultRegistry(options: CreateDefaultRegistryOptions = {}): ActionRegistry {
+    const actions: SchedulerAction[] = [new LogAction()];
+    if (options.queueStatsDaoProvider) {
+        actions.push(new QueueStatsAction(options.queueStatsDaoProvider, options.systemBus ?? null));
+    }
+    if (options.healthPingWriter) {
+        actions.push(new HealthPingAction(options.healthPingWriter, options.healthPingPath));
+    }
+    return new ActionRegistry(actions);
+}
+
 export type { ScheduledAction } from './types';

package/src/scheduler/cloudflare.ts

@@ -15,6 +15,12 @@ interface CfEventContext {
     waitUntil(promise: Promise<unknown>): void;
 }
 
+/**
+ * Scheduler adapter for Cloudflare Workers Cron Triggers.
+ *
+ * Register cron→action pairs, then call {@link CloudflareSchedulerAdapter.handleScheduledEvent}
+ * from the Worker's `scheduled()` export.
+ */
 export class CloudflareSchedulerAdapter implements SchedulerAdapter {
     private readonly entries = new Map<string, ScheduledAction>();
 

package/src/scheduler/factory.ts

@@ -6,6 +6,7 @@ import type { ScheduledAction, SchedulerAdapter } from './types';
 
 let runtimeAdapter: SchedulerAdapter | undefined;
 
+/** Set the runtime scheduler adapter. Call before {@link initScheduler}. */
 export function setSchedulerAdapter(adapter: SchedulerAdapter): void {
     runtimeAdapter = adapter;
 }
@@ -15,6 +16,7 @@ export function resetSchedulerAdapter(): void {
     runtimeAdapter = undefined;
 }
 
+/** Get the currently configured scheduler adapter, or `undefined` if not set. */
 export function getSchedulerAdapter(): SchedulerAdapter | undefined {
     return runtimeAdapter;
 }

package/src/scheduler/index.ts

@@ -1,5 +1,16 @@
-export { CloudflareSchedulerAdapter } from './cloudflare';
+export {
+    ActionRegistry,
+    type CreateDefaultRegistryOptions,
+    createDefaultRegistry,
+    HealthPingAction,
+    type HealthPingWriter,
+    LogAction,
+    QueueStatsAction,
+    type QueueStatsDaoProvider,
+    type SchedulerAction,
+    toScheduledAction,
+} from './action';
 export { getSchedulerAdapter, initScheduler, resetSchedulerAdapter, setSchedulerAdapter } from './factory';
-export { NodeSchedulerAdapter } from './node';
 export { NoopSchedulerAdapter } from './noop';
 export type { ScheduledAction, SchedulerAdapter } from './types';
+export { wrapScheduledHandler } from './wrap-handler';

package/src/scheduler/node.ts

@@ -36,6 +36,10 @@ interface ScheduledEntry {
     timer?: ReturnType<typeof setInterval>;
 }
 
+/**
+ * Scheduler adapter for Node.js using a setInterval-based approach.
+ * No external cron library dependency — cron expressions are parsed minimally.
+ */
 export class NodeSchedulerAdapter implements SchedulerAdapter {
     private readonly entries: ScheduledEntry[] = [];
     private running = false;

package/src/scheduler/noop.ts

@@ -3,6 +3,7 @@
  */
 import type { ScheduledAction, SchedulerAdapter } from './types';
 
+/** Scheduler adapter that discards all registrations — for testing and environments without scheduling. */
 export class NoopSchedulerAdapter implements SchedulerAdapter {
     constructor() {}
 

package/src/scheduler/wrap-handler.ts

@@ -0,0 +1,50 @@
+import type { EventBus } from '../event-bus/event-bus';
+import type { SchedulerEvents } from '../events';
+import { addSpanAttributes, addSpanEvent, traceAsync } from '../telemetry/tracing';
+import type { ScheduledAction } from './types';
+
+/**
+ * Wrap a scheduled action with OTel tracing, duration measurement, and
+ * `scheduler.job.executed` event emission.
+ *
+ * Composes *on top of* the adapter's inline metrics (executed/failed/duration
+ * counters live in the Node/Cloudflare adapters) — this wrapper adds the named
+ * tracing span and the lifecycle event, neither of which the adapters provide.
+ * Opt-in: wrap an action before registering it when you want that visibility.
+ *
+ * @param name - Job name, surfaced as `scheduler.job_name` on the span/event.
+ * @param action - The action to wrap (new no-arg `ScheduledAction` signature).
+ * @param systemBus - Optional bus to emit `scheduler.job.executed` on.
+ */
+export function wrapScheduledHandler(
+    name: string,
+    action: ScheduledAction,
+    systemBus?: EventBus<SchedulerEvents> | null,
+): ScheduledAction {
+    return async () => {
+        const startTime = performance.now();
+
+        return traceAsync('scheduler.job', async (span) => {
+            addSpanAttributes({ 'scheduler.job_name': name });
+
+            let execError: string | undefined;
+            try {
+                await action();
+            } catch (error) {
+                execError = error instanceof Error ? error.message : String(error);
+                addSpanEvent('scheduler.job.error', { 'scheduler.error': execError });
+                span.setStatus({ code: 2, message: execError }); // ERROR
+                throw error;
+            } finally {
+                const durationMs = Math.round(performance.now() - startTime);
+                addSpanAttributes({ 'scheduler.duration_ms': durationMs });
+
+                systemBus?.emit('scheduler.job.executed', {
+                    name,
+                    durationMs,
+                    ...(execError !== undefined ? { error: execError } : {}),
+                });
+            }
+        });
+    };
+}

package/src/scheduler-cloudflare.ts

@@ -0,0 +1 @@
+export { CloudflareSchedulerAdapter } from './scheduler/cloudflare';

package/src/scheduler-node.ts

@@ -0,0 +1 @@
+export { NodeSchedulerAdapter } from './scheduler/node';

package/src/telemetry/config.ts

@@ -2,6 +2,10 @@
  * Telemetry configuration interface.
  */
 
+/**
+ * Full telemetry configuration: master enable switch, service name,
+ * environment, and debug-level DB statement capture.
+ */
 export interface TelemetryConfig {
     /** Master switch — when false, all tracing degrades to no-ops. */
     enabled: boolean;

package/src/telemetry/metrics.ts

@@ -8,6 +8,7 @@ export type { Counter, Histogram } from '@opentelemetry/api';
 
 let metricsInitialized = false;
 
+/** Whether the metrics subsystem has been initialized via {@link initMetrics}. */
 export function isMetricsInitialized(): boolean {
     return metricsInitialized;
 }
@@ -40,67 +41,81 @@ function getOrCreateHistogram(key: string, name: string, description: string, un
 
 // ── HTTP client ─────────────────────────────────────────────────────
 
+/** Counter for total outbound HTTP requests, tagged by method and status code. */
 export function getHttpClientRequestTotal(): Counter {
     return getOrCreateCounter('httpCliReq', 'http.client.request.total', 'Total outbound HTTP requests', '{request}');
 }
 
+/** Histogram for outbound HTTP request duration in milliseconds. */
 export function getHttpClientRequestDuration(): Histogram {
     return getOrCreateHistogram('httpCliDur', 'http.client.request.duration', 'Outbound HTTP request duration');
 }
 
+/** Counter for outbound HTTP errors, tagged by error type. */
 export function getHttpClientRequestErrors(): Counter {
     return getOrCreateCounter('httpCliErr', 'http.client.request.errors', 'Outbound HTTP errors', '{error}');
 }
 
 // ── Event bus ───────────────────────────────────────────────────────
 
+/** Counter for total event bus emits. */
 export function getEventbusEmitsTotal(): Counter {
     return getOrCreateCounter('ebEmit', 'eventbus.emits.total', 'Total event bus emits', '{emit}');
 }
 
+/** Counter for event bus handler errors. */
 export function getEventbusErrorsTotal(): Counter {
     return getOrCreateCounter('ebErr', 'eventbus.errors.total', 'Event bus errors', '{error}');
 }
 
 // ── Queue ───────────────────────────────────────────────────────────
 
+/** Counter for total jobs enqueued. */
 export function getQueueJobEnqueuedTotal(): Counter {
     return getOrCreateCounter('qEnq', 'queue.jobs.enqueued', 'Total jobs enqueued', '{job}');
 }
 
+/** Counter for total jobs completed successfully. */
 export function getQueueJobCompletedTotal(): Counter {
     return getOrCreateCounter('qComp', 'queue.jobs.completed', 'Total jobs completed', '{job}');
 }
 
+/** Counter for total jobs that failed (exhausted retries). */
 export function getQueueJobFailedTotal(): Counter {
     return getOrCreateCounter('qFail', 'queue.jobs.failed', 'Total jobs failed', '{job}');
 }
 
+/** Histogram for job processing duration in milliseconds. */
 export function getQueueJobProcessingDuration(): Histogram {
     return getOrCreateHistogram('qProcDur', 'queue.jobs.processing_duration', 'Job processing duration');
 }
 
 // ── Scheduler ───────────────────────────────────────────────────────
 
+/** Counter for total scheduled job executions. */
 export function getSchedulerJobExecutedTotal(): Counter {
     return getOrCreateCounter('schedExec', 'scheduler.jobs.executed', 'Total scheduled job executions', '{execution}');
 }
 
+/** Histogram for scheduled job execution duration in milliseconds. */
 export function getSchedulerJobDuration(): Histogram {
     return getOrCreateHistogram('schedDur', 'scheduler.jobs.duration', 'Scheduled job duration');
 }
 
+/** Counter for failed scheduled job executions. */
 export function getSchedulerJobFailedTotal(): Counter {
     return getOrCreateCounter('schedFail', 'scheduler.jobs.failed', 'Failed scheduled jobs', '{failure}');
 }
 
 // ── Lifecycle ───────────────────────────────────────────────────────
 
+/** Mark the metrics subsystem as initialized. Idempotent. */
 export function initMetrics(): void {
     if (metricsInitialized) return;
     metricsInitialized = true;
 }
 
+/** Clear the instrument cache and mark metrics as uninitialized. */
 export function shutdownMetrics(): Promise<void> {
     // 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
@@ -112,6 +127,10 @@ export function shutdownMetrics(): Promise<void> {
     return Promise.resolve();
 }
 
+/**
+ * Reset all metrics state: clear instrument cache, mark uninitialized,
+ * and disable the global meter. For testing only.
+ */
 export function _resetMetrics(): void {
     for (const key of Object.keys(instruments)) {
         instruments[key] = undefined;

package/src/telemetry/sdk.ts

@@ -17,6 +17,7 @@ const TRACER_VERSION = '0.1.0';
 let telemetryInitialized = false;
 let resolvedConfig: TelemetryConfig = getTelemetryConfig();
 
+/** Get the resolved telemetry configuration (defaults + overrides). */
 export function getResolvedConfig(): TelemetryConfig {
     return resolvedConfig;
 }
@@ -31,6 +32,7 @@ export function initTelemetry(config?: Partial<TelemetryConfig>): void {
     telemetryInitialized = true;
 }
 
+/** Mark telemetry as uninitialized. Does not shut down the OTel provider. */
 export function shutdownTelemetry(): Promise<void> {
     telemetryInitialized = false;
     return Promise.resolve();
@@ -41,10 +43,12 @@ export function getTracer(): Tracer {
     return trace.getTracer(TRACER_NAME, TRACER_VERSION);
 }
 
+/** Whether telemetry is initialized and enabled. */
 export function isTelemetryEnabled(): boolean {
     return telemetryInitialized && resolvedConfig.enabled;
 }
 
+/** Reset the telemetry subsystem to its uninitialized state. For testing. */
 export function _resetTelemetry(): void {
     telemetryInitialized = false;
     resolvedConfig = getTelemetryConfig();

package/src/telemetry/tracing.ts

@@ -5,6 +5,10 @@
 import { context, type Span, type SpanOptions, type Tracer, trace } from '@opentelemetry/api';
 import { getTracer } from './sdk';
 
+/**
+ * Execute an async function within an active OTel span.
+ * The span is automatically ended and its status set on error.
+ */
 export async function traceAsync<T>(
     name: string,
     fn: (span: Span) => Promise<T>,
@@ -24,6 +28,10 @@ export async function traceAsync<T>(
     });
 }
 
+/**
+ * Execute a synchronous function within an active OTel span.
+ * The span is automatically ended and its status set on error.
+ */
 export function traceSync<T>(name: string, fn: (span: Span) => T, options?: SpanOptions, tracer?: Tracer): T {
     const resolvedTracer = tracer ?? getTracer();
     return resolvedTracer.startActiveSpan(name, options ?? {}, (span) => {
@@ -38,6 +46,7 @@ export function traceSync<T>(name: string, fn: (span: Span) => T, options?: Span
     });
 }
 
+/** Set key-value attributes on the currently active span. No-op when no span is recording. */
 export function addSpanAttributes(attributes: Record<string, string | number | boolean>): void {
     const span = trace.getActiveSpan();
     if (span?.isRecording()) {
@@ -45,6 +54,7 @@ export function addSpanAttributes(attributes: Record<string, string | number | b
     }
 }
 
+/** Add a named event to the currently active span. No-op when no span is recording. */
 export function addSpanEvent(name: string, attributes?: Record<string, string | number | boolean>): void {
     const span = trace.getActiveSpan();
     if (span?.isRecording()) {
@@ -52,10 +62,12 @@ export function addSpanEvent(name: string, attributes?: Record<string, string |
     }
 }
 
+/** Get the currently active span from context, or `undefined`. */
 export function getActiveSpan(): Span | undefined {
     return trace.getActiveSpan() ?? undefined;
 }
 
+/** Execute a function with a specific span set as the active span in context. */
 export function withSpan<T>(span: Span, fn: () => T): T {
     return context.with(trace.setSpan(context.active(), span), fn);
 }