@gobing-ai/ts-infra 0.1.0

package/src/job-queue/types.ts

@@ -0,0 +1,60 @@
+/**
+ * Job queue types for async work processing with retry.
+ *
+ * **Types only** — the DB-backed `DbQueue` and `DbConsumer` implementations
+ * that drive the job-queue subsystem live in `@spur/core`. These interfaces
+ * are provided here so `EventBus` and other infra components can reference
+ * the queue contract without a circular dependency on the DB layer.
+ */
+
+export interface Job<T = unknown> {
+    id: string;
+    type: string;
+    payload: T;
+    status: 'pending' | 'processing' | 'completed' | 'failed';
+    attempts: number;
+    maxRetries: number;
+    createdAt: number;
+    updatedAt: number;
+    nextRetryAt: number | null;
+    lastError: string | null;
+    processingAt: number | null;
+}
+
+export interface EnqueueOptions {
+    maxRetries?: number;
+    delay?: number;
+    ttlMs?: number;
+}
+
+export interface JobQueue<T = unknown> {
+    enqueue(type: string, payload: T, options?: EnqueueOptions): Promise<string>;
+    enqueueBatch(jobs: Array<{ type: string; payload: T } & EnqueueOptions>): Promise<string[]>;
+}
+
+export type JobHandler<T = unknown> = (job: Job<T>) => Promise<void>;
+
+export interface QueueStats {
+    pending: number;
+    processing: number;
+    completed: number;
+    failed: number;
+}
+
+export interface QueueConsumerConfig {
+    pollInterval?: number;
+    batchSize?: number;
+    maxConcurrency?: number;
+    visibilityTimeout?: number;
+    baseDelay?: number;
+    maxDelay?: number;
+    drainTimeoutMs?: number;
+    maxPollBackoff?: number;
+}
+
+export interface QueueConsumer<T = unknown> {
+    register(type: string, handler: JobHandler<T>): void;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    stats(): Promise<QueueStats>;
+}

package/src/logger.ts

@@ -0,0 +1,123 @@
+/**
+ * Structured JSON logger with levels (trace/debug/info/warn/error/fatal).
+ *
+ * No external dependencies — console-based implementation.
+ */
+
+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,
+};
+
+export interface Logger {
+    trace(msg: string, data?: Record<string, unknown>): void;
+    debug(msg: string, data?: Record<string, unknown>): void;
+    info(msg: string, data?: Record<string, unknown>): void;
+    warn(msg: string, data?: Record<string, unknown>): void;
+    error(msg: string, data?: Record<string, unknown>): void;
+    fatal(msg: string, data?: Record<string, unknown>): void;
+    child(context: Record<string, unknown>): Logger;
+}
+
+class ConsoleLogger implements Logger {
+    private readonly context: Record<string, unknown>;
+
+    constructor(
+        private readonly category: string,
+        private readonly minLevel: LogLevel = 'info',
+        context: Record<string, unknown> = {},
+    ) {
+        this.context = { category, ...context };
+    }
+
+    private log(level: LogLevel, msg: string, data?: Record<string, unknown>): void {
+        if (LEVEL_ORDER[level] < LEVEL_ORDER[this.minLevel]) return;
+        if (globalMuted) return;
+
+        const entry = {
+            level,
+            message: msg,
+            timestamp: new Date().toISOString(),
+            ...this.context,
+            ...data,
+        };
+
+        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);
+        }
+    }
+
+    trace(msg: string, data?: Record<string, unknown>): void {
+        this.log('trace', msg, data);
+    }
+    debug(msg: string, data?: Record<string, unknown>): void {
+        this.log('debug', msg, data);
+    }
+    info(msg: string, data?: Record<string, unknown>): void {
+        this.log('info', msg, data);
+    }
+    warn(msg: string, data?: Record<string, unknown>): void {
+        this.log('warn', msg, data);
+    }
+    error(msg: string, data?: Record<string, unknown>): void {
+        this.log('error', msg, data);
+    }
+    fatal(msg: string, data?: Record<string, unknown>): void {
+        this.log('fatal', msg, data);
+    }
+
+    child(context: Record<string, unknown>): Logger {
+        return new ConsoleLogger(this.category, this.minLevel, { ...this.context, ...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.
+ */
+export function getLogger(category: string): Logger {
+    const existing = loggers.get(category);
+    if (existing) return existing;
+
+    const logger = new ConsoleLogger(category, globalLevel);
+    loggers.set(category, logger);
+    return logger;
+}
+
+/**
+ * Initialize the logger subsystem with a minimum log level.
+ */
+export function initializeLogger(level: LogLevel = 'info'): void {
+    globalLevel = level;
+    loggers.clear();
+}

package/src/scheduler/action.ts

@@ -0,0 +1,4 @@
+/**
+ * Scheduler action type re-export.
+ */
+export type { ScheduledAction } from './types';

package/src/scheduler/cloudflare.ts

@@ -0,0 +1,45 @@
+/**
+ * Cloudflare Workers scheduler adapter using Cron Triggers.
+ * Uses minimal local type declarations — no @cloudflare/workers-types dependency.
+ */
+import type { ScheduledAction, SchedulerAdapter } from './types';
+
+interface CfScheduledEvent {
+    cron: string;
+    scheduledTime: number;
+    waitUntil(promise: Promise<unknown>): void;
+}
+
+interface CfEventContext {
+    waitUntil(promise: Promise<unknown>): void;
+}
+
+export class CloudflareSchedulerAdapter implements SchedulerAdapter {
+    private readonly entries = new Map<string, ScheduledAction>();
+
+    constructor() {}
+
+    register(cron: string, action: ScheduledAction): void {
+        this.entries.set(cron, action);
+    }
+
+    async start(): Promise<void> {
+        // Cloudflare Workers use cron triggers defined in wrangler.toml.
+        // The `scheduled()` handler should call `handleScheduledEvent()`.
+    }
+
+    async stop(): Promise<void> {
+        this.entries.clear();
+    }
+
+    /**
+     * Handle a Cloudflare Workers Cron Trigger event.
+     * Call this from the Worker's `scheduled()` export.
+     */
+    handleScheduledEvent(event: CfScheduledEvent, ctx: CfEventContext): void {
+        const action = this.entries.get(event.cron);
+        if (action) {
+            ctx.waitUntil(action());
+        }
+    }
+}

package/src/scheduler/factory.ts

@@ -0,0 +1,57 @@
+/**
+ * Scheduler factory — selects adapter based on runtime.
+ */
+import type { ScheduledAction, SchedulerAdapter } from './types';
+
+let runtimeAdapter: SchedulerAdapter | undefined;
+
+export function setSchedulerAdapter(adapter: SchedulerAdapter): void {
+    runtimeAdapter = adapter;
+}
+
+/** Reset the scheduler adapter singleton. For testing. */
+export function resetSchedulerAdapter(): void {
+    runtimeAdapter = undefined;
+}
+
+export function getSchedulerAdapter(): SchedulerAdapter | undefined {
+    return runtimeAdapter;
+}
+
+/**
+ * Initialize the scheduler adapter and register cron entries.
+ *
+ * MUST be called before `adapter.start()`. If the adapter is already
+ * running, newly registered entries will NOT be started until the next
+ * `start()` call.
+ *
+ * Returns the configured adapter (defaults to noop if none set).
+ */
+export function initScheduler(cronEntries?: Array<[string, ScheduledAction]>): SchedulerAdapter {
+    // Default: create a noop adapter. Apps inject their own via setSchedulerAdapter.
+    if (!runtimeAdapter) {
+        runtimeAdapter = createNoopScheduler();
+    }
+
+    if (cronEntries) {
+        for (const [cron, action] of cronEntries) {
+            runtimeAdapter.register(cron, action);
+        }
+    }
+
+    return runtimeAdapter;
+}
+
+function createNoopScheduler(): SchedulerAdapter {
+    return {
+        register(): void {
+            /* noop */
+        },
+        start(): Promise<void> {
+            return Promise.resolve();
+        },
+        stop(): Promise<void> {
+            return Promise.resolve();
+        },
+    };
+}

package/src/scheduler/index.ts

@@ -0,0 +1,5 @@
+export { CloudflareSchedulerAdapter } from './cloudflare';
+export { getSchedulerAdapter, initScheduler, resetSchedulerAdapter, setSchedulerAdapter } from './factory';
+export { NodeSchedulerAdapter } from './node';
+export { NoopSchedulerAdapter } from './noop';
+export type { ScheduledAction, SchedulerAdapter } from './types';

package/src/scheduler/node.ts

@@ -0,0 +1,83 @@
+/**
+ * Node.js scheduler adapter using a simple setInterval-based approach.
+ * No external cron library dependency — cron expressions are parsed minimally.
+ */
+import type { ScheduledAction, SchedulerAdapter } from './types';
+
+/** Simple helper to parse cron-like interval strings into milliseconds. */
+function parseInterval(cron: string): number {
+    // Support simple patterns: "* * * * *" (every minute), "*/5 * * * *" (every 5 min)
+    // Also support direct ms strings like "60000"
+    const num = Number(cron);
+    if (!Number.isNaN(num)) return num;
+
+    const parts = cron.trim().split(/\s+/);
+    if (parts.length === 5 && parts[0] === '*') {
+        return 60_000; // every minute default
+    }
+
+    // */N pattern
+    const match = parts[0]?.match(/^\*\/(\d+)$/);
+    if (match) {
+        return Number(match[1]) * 60_000;
+    }
+
+    return 60_000; // fallback: every minute
+}
+
+interface ScheduledEntry {
+    cron: string;
+    action: ScheduledAction;
+    timer?: ReturnType<typeof setInterval>;
+}
+
+export class NodeSchedulerAdapter implements SchedulerAdapter {
+    private readonly entries: ScheduledEntry[] = [];
+    private running = false;
+
+    constructor() {}
+
+    register(cron: string, action: ScheduledAction): void {
+        this.entries.push({ cron, action });
+        if (this.running) {
+            const last = this.entries[this.entries.length - 1];
+            if (last) {
+                this.startEntry(last);
+            }
+        }
+    }
+
+    async start(): Promise<void> {
+        if (this.running) return;
+
+        this.running = true;
+        for (const entry of this.entries) {
+            this.startEntry(entry);
+        }
+    }
+
+    async stop(): Promise<void> {
+        this.running = false;
+        for (const entry of this.entries) {
+            if (entry.timer) {
+                clearInterval(entry.timer);
+                entry.timer = undefined;
+            }
+        }
+    }
+
+    private startEntry(entry: ScheduledEntry): void {
+        if (entry.timer) return;
+
+        const interval = parseInterval(entry.cron);
+        entry.timer = setInterval(this._onScheduledTick.bind(this, entry), interval);
+    }
+
+    private async _onScheduledTick(entry: ScheduledEntry): Promise<void> {
+        try {
+            await entry.action();
+        } catch {
+            // Swallow — scheduler errors should not crash the process
+        }
+    }
+}

package/src/scheduler/noop.ts

@@ -0,0 +1,20 @@
+/**
+ * No-op scheduler adapter for testing and environments without scheduling.
+ */
+import type { ScheduledAction, SchedulerAdapter } from './types';
+
+export class NoopSchedulerAdapter implements SchedulerAdapter {
+    constructor() {}
+
+    register(_cron: string, _action: ScheduledAction): void {
+        // noop
+    }
+
+    async start(): Promise<void> {
+        // noop
+    }
+
+    async stop(): Promise<void> {
+        // noop
+    }
+}

package/src/scheduler/types.ts

@@ -0,0 +1,13 @@
+/**
+ * Scheduler types and interface.
+ */
+
+/** Signature for scheduled action handlers. */
+export type ScheduledAction = () => Promise<void>;
+
+/** Abstract scheduler interface — implementations for Node (node-cron) and Cloudflare. */
+export interface SchedulerAdapter {
+    register(cron: string, action: ScheduledAction): void;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+}

package/src/telemetry/config.ts

@@ -0,0 +1,63 @@
+/**
+ * Telemetry configuration interface.
+ */
+
+export interface TelemetryConfig {
+    /** Master switch — when false, all tracing degrades to no-ops. */
+    enabled: boolean;
+    /** Logical service name emitted on every span. */
+    serviceName: string;
+    /** Deployment environment (development, staging, production). */
+    environment: string;
+    /** OTLP exporter endpoint (e.g. `http://localhost:4318/v1/traces`). */
+    exporterEndpoint?: string | undefined;
+    /** Export protocol — only `http` is supported in v1. */
+    exporterProtocol: 'http';
+    /**
+     * Debug-only DB statement capture.
+     *
+     * When true, DB spans may include sanitized SQL text in a `db.statement`
+     * attribute. SQL text is redacted — parameter values, literals, and
+     * identifiers are stripped before capture.
+     *
+     * Default: `false`. Controlled by `OTEL_DB_STATEMENT_DEBUG` env var.
+     */
+    dbStatementDebug: boolean;
+}
+
+/**
+ * Partial telemetry config from the centralized config system.
+ */
+export interface TelemetryConfigPartial {
+    enabled?: boolean | undefined;
+    serviceName?: string | undefined;
+    environment?: string | undefined;
+    exporterEndpoint?: string | undefined;
+    dbStatementDebug?: boolean | undefined;
+    /** Deployment environment fallback (from app.env). */
+    appEnv?: string | undefined;
+}
+
+const DEFAULTS = {
+    enabled: true as const,
+    serviceName: 'ts-libs' as const,
+    environment: 'development' as const,
+    exporterProtocol: 'http' as const,
+};
+
+/**
+ * Resolve the full telemetry config by merging a partial override with defaults.
+ */
+export function getTelemetryConfig(configPartial: TelemetryConfigPartial = {}): TelemetryConfig {
+    const enabled = configPartial.enabled ?? DEFAULTS.enabled;
+    const serviceName = configPartial.serviceName ?? DEFAULTS.serviceName;
+
+    return {
+        enabled,
+        serviceName,
+        environment: configPartial.environment ?? configPartial.appEnv ?? DEFAULTS.environment,
+        exporterEndpoint: configPartial.exporterEndpoint,
+        exporterProtocol: DEFAULTS.exporterProtocol,
+        dbStatementDebug: configPartial.dbStatementDebug ?? false,
+    };
+}

package/src/telemetry/db-sanitize.ts

@@ -0,0 +1,79 @@
+/**
+ * SQL sanitization for debug-mode DB statement capture.
+ *
+ * Strips parameter values, string literals, numeric literals, and
+ * identifier-specific data from SQL text before it is attached to spans.
+ */
+
+/**
+ * Redact string literals and numeric literals from SQL text.
+ */
+export function sanitizeSql(sql: string): string {
+    let result = '';
+    let i = 0;
+    const len = sql.length;
+
+    while (i < len) {
+        const code = sql.charCodeAt(i);
+
+        // Quote characters: ' (39) or " (34)
+        if (code === 39 || code === 34) {
+            const quote = code;
+            i++;
+            while (i < len) {
+                if (sql.charCodeAt(i) === quote) {
+                    if (sql.charCodeAt(i + 1) === quote) {
+                        i += 2;
+                        continue;
+                    }
+                    i++;
+                    break;
+                }
+                i++;
+            }
+            result += '?';
+            continue;
+        }
+
+        // Numeric literal
+        if (code >= 48 && code <= 57) {
+            const prev = result.length > 0 ? result.charCodeAt(result.length - 1) : 0;
+            const isIdentifierContinuation =
+                (prev >= 65 && prev <= 90) || (prev >= 97 && prev <= 122) || prev === 95 || (prev >= 48 && prev <= 57);
+
+            if (!isIdentifierContinuation) {
+                while (i < len) {
+                    const c = sql.charCodeAt(i);
+                    if (c < 48 || c > 57) break;
+                    i++;
+                }
+                if (i < len && sql.charCodeAt(i) === 46 && i + 1 < len) {
+                    const next = sql.charCodeAt(i + 1);
+                    if (next >= 48 && next <= 57) {
+                        i++;
+                        while (i < len) {
+                            const c = sql.charCodeAt(i);
+                            if (c < 48 || c > 57) break;
+                            i++;
+                        }
+                    }
+                }
+                result += '?';
+                continue;
+            }
+        }
+
+        result += sql[i] ?? '';
+        i++;
+    }
+
+    return result;
+}
+
+/**
+ * Extract the SQL operation keyword (SELECT, INSERT, UPDATE, DELETE, etc.)
+ */
+export function extractSqlOperation(sql: string): string | undefined {
+    const match = sql.trim().match(/^\s*(SELECT|INSERT|UPDATE|DELETE|CREATE|ALTER|DROP|PRAGMA)\b/i);
+    return match?.[1]?.toUpperCase();
+}

package/src/telemetry/index.ts

@@ -0,0 +1,29 @@
+export { getTelemetryConfig, type TelemetryConfig, type TelemetryConfigPartial } from './config';
+export { extractSqlOperation, sanitizeSql } from './db-sanitize';
+export {
+    type Counter,
+    getDbOperationDuration,
+    getDbOperationErrors,
+    getDbOperationTotal,
+    getEventbusEmitsTotal,
+    getEventbusErrorsTotal,
+    getHttpClientRequestDuration,
+    getHttpClientRequestErrors,
+    getHttpClientRequestTotal,
+    getHttpServerRequestDuration,
+    getHttpServerRequestErrors,
+    getHttpServerRequestTotal,
+    getQueueJobCompletedTotal,
+    getQueueJobEnqueuedTotal,
+    getQueueJobFailedTotal,
+    getQueueJobProcessingDuration,
+    getSchedulerJobDuration,
+    getSchedulerJobExecutedTotal,
+    getSchedulerJobFailedTotal,
+    type Histogram,
+    initMetrics,
+    shutdownMetrics,
+} from './metrics';
+export { getTracer, initTelemetry, isTelemetryEnabled, shutdownTelemetry } from './sdk';
+export type { Span, SpanOptions, Tracer } from './tracing';
+export { addSpanAttributes, addSpanEvent, getActiveSpan, traceAsync, traceSync, withSpan } from './tracing';