@gobing-ai/ts-infra 0.1.0

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

@@ -0,0 +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"}

package/dist/telemetry/tracing.js

@@ -0,0 +1,54 @@
+/**
+ * High-level tracing helpers for application code.
+ */
+import { context, trace } from '@opentelemetry/api';
+import { getTracer } from './sdk.js';
+export async function traceAsync(name, fn, options, tracer) {
+    const resolvedTracer = tracer ?? getTracer();
+    return resolvedTracer.startActiveSpan(name, options ?? {}, async (span) => {
+        try {
+            return await fn(span);
+        }
+        catch (err) {
+            span.setStatus({ code: 2, message: err instanceof Error ? err.message : String(err) });
+            throw err;
+        }
+        finally {
+            span.end();
+        }
+    });
+}
+export function traceSync(name, fn, options, tracer) {
+    const resolvedTracer = tracer ?? getTracer();
+    return resolvedTracer.startActiveSpan(name, options ?? {}, (span) => {
+        try {
+            return fn(span);
+        }
+        catch (err) {
+            span.setStatus({ code: 2, message: err instanceof Error ? err.message : String(err) });
+            throw err;
+        }
+        finally {
+            span.end();
+        }
+    });
+}
+export function addSpanAttributes(attributes) {
+    const span = trace.getActiveSpan();
+    if (span?.isRecording()) {
+        span.setAttributes(attributes);
+    }
+}
+export function addSpanEvent(name, attributes) {
+    const span = trace.getActiveSpan();
+    if (span?.isRecording()) {
+        span.addEvent(name, attributes);
+    }
+}
+export function getActiveSpan() {
+    return trace.getActiveSpan() ?? undefined;
+}
+export function withSpan(span, fn) {
+    return context.with(trace.setSpan(context.active(), span), fn);
+}
+export { context, propagation, trace } from './sdk.js';

package/package.json

@@ -0,0 +1,50 @@
+{
+    "name": "@gobing-ai/ts-infra",
+    "version": "0.1.0",
+    "description": "@gobing-ai/ts-infra — Infrastructure backbone: event bus, job queue, scheduler, telemetry, API client, and logging.",
+    "type": "module",
+    "private": false,
+    "sideEffects": false,
+    "license": "Apache-2.0",
+    "main": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "import": "./dist/index.js"
+        }
+    },
+    "files": [
+        "dist",
+        "src",
+        "README.md"
+    ],
+    "scripts": {
+        "build": "tsc -p tsconfig.build.json && bun ../../scripts/fix-dist-esm-extensions.ts dist",
+        "test": "NODE_ENV=test bun test --coverage --coverage-dir=.coverage --reporter=dots",
+        "test:full": "NODE_ENV=test bun test --update-snapshots --coverage --coverage-dir=.coverage",
+        "typecheck": "tsc --noEmit",
+        "lint": "biome check . && bun run typecheck",
+        "format": "biome check . --write",
+        "check": "bun run lint && bun run test",
+        "prepublishOnly": "bun run build",
+        "release": "npm publish --access public"
+    },
+    "dependencies": {
+        "@gobing-ai/ts-db": "^0.1.0",
+        "@gobing-ai/ts-runtime": "^0.1.0"
+    },
+    "peerDependencies": {
+        "@opentelemetry/api": "^1.9.0"
+    },
+    "devDependencies": {
+        "@types/bun": "1.3.14",
+        "@opentelemetry/api": "^1.9.0",
+        "@opentelemetry/sdk-trace-node": "^1.30.0",
+        "@opentelemetry/sdk-metrics": "^1.30.0",
+        "@opentelemetry/semantic-conventions": "^1.30.0"
+    },
+    "publishConfig": {
+        "access": "public"
+    }
+}

package/src/api-client.ts

@@ -0,0 +1,162 @@
+/**
+ * Typed HTTP client builder wrapping fetch with OTel tracing.
+ */
+import { type Span, SpanKind } from '@opentelemetry/api';
+import {
+    ATTR_HTTP_REQUEST_METHOD,
+    ATTR_HTTP_RESPONSE_STATUS_CODE,
+    ATTR_URL_FULL,
+} from '@opentelemetry/semantic-conventions';
+import {
+    getHttpClientRequestDuration,
+    getHttpClientRequestErrors,
+    getHttpClientRequestTotal,
+} from './telemetry/metrics';
+import { traceAsync } from './telemetry/tracing';
+
+// ── Types ───────────────────────────────────────────────────────────
+
+export interface APIClientConfig {
+    baseUrl: string;
+    defaultHeaders?: Record<string, string>;
+    timeout?: number;
+    fetch?: typeof globalThis.fetch;
+}
+
+export interface RequestOptions {
+    headers?: Record<string, string>;
+    timeout?: number;
+    operationName?: string;
+    signal?: AbortSignal;
+}
+
+export class APIError extends Error {
+    constructor(
+        public readonly status: number,
+        public readonly body: string,
+    ) {
+        super(`HTTP ${status}: ${body.slice(0, 200)}`);
+        this.name = 'APIError';
+    }
+}
+
+// ── Client ──────────────────────────────────────────────────────────
+
+export class APIClient {
+    private readonly baseUrl: string;
+    private readonly defaultHeaders: Record<string, string>;
+    private readonly timeout: number;
+    private readonly fetchFn: typeof globalThis.fetch;
+
+    constructor(config: APIClientConfig) {
+        this.baseUrl = config.baseUrl.replace(/\/+$/, '');
+        this.defaultHeaders = config.defaultHeaders ?? {};
+        this.timeout = config.timeout ?? 30_000;
+        this.fetchFn = config.fetch ?? globalThis.fetch;
+    }
+
+    private buildUrl(path: string): string {
+        return `${this.baseUrl}${path.startsWith('/') ? path : `/${path}`}`;
+    }
+
+    private async request<T>(method: string, path: string, body?: unknown, opts?: RequestOptions): Promise<T> {
+        const url = this.buildUrl(path);
+        const headers: Record<string, string> = {
+            'Content-Type': 'application/json',
+            ...this.defaultHeaders,
+            ...opts?.headers,
+        };
+
+        const operationName = opts?.operationName ?? `HTTP ${method} ${url}`;
+
+        return traceAsync(
+            operationName,
+            async (span: Span) => {
+                span.setAttribute(ATTR_HTTP_REQUEST_METHOD, method);
+                span.setAttribute(ATTR_URL_FULL, url);
+
+                const controller = new AbortController();
+                const timeoutMs = opts?.timeout ?? this.timeout;
+                let timer: ReturnType<typeof setTimeout> | undefined;
+
+                if (timeoutMs > 0) {
+                    timer = setTimeout(() => controller.abort(), timeoutMs);
+                }
+
+                const combinedSignal = opts?.signal
+                    ? AbortSignal.any([opts.signal, controller.signal])
+                    : controller.signal;
+
+                try {
+                    const start = performance.now();
+
+                    const response = await this.fetchFn(url, {
+                        method,
+                        headers,
+                        body: body !== undefined ? JSON.stringify(body) : undefined,
+                        signal: combinedSignal,
+                    });
+
+                    if (timer) clearTimeout(timer);
+
+                    span.setAttribute(ATTR_HTTP_RESPONSE_STATUS_CODE, response.status);
+
+                    getHttpClientRequestTotal().add(1, {
+                        'http.request.method': method,
+                        'http.response.status_code': response.status,
+                    });
+
+                    const duration = performance.now() - start;
+                    getHttpClientRequestDuration().record(duration, {
+                        'http.request.method': method,
+                        'http.response.status_code': response.status,
+                    });
+
+                    if (!response.ok) {
+                        const text = await response.text();
+                        getHttpClientRequestErrors().add(1, {
+                            'http.request.method': method,
+                            'error.type': `HTTP_${response.status}`,
+                        });
+                        throw new APIError(response.status, text);
+                    }
+
+                    const contentType = response.headers.get('content-type') ?? '';
+                    if (contentType.includes('application/json')) {
+                        return (await response.json()) as T;
+                    }
+
+                    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,
+                            'error.type': error instanceof Error ? error.name : 'Unknown',
+                        });
+                    }
+
+                    throw error;
+                }
+            },
+            { kind: SpanKind.CLIENT },
+        );
+    }
+
+    async get<T>(path: string, opts?: RequestOptions): Promise<T> {
+        return this.request<T>('GET', path, undefined, opts);
+    }
+
+    async post<T>(path: string, body?: unknown, opts?: RequestOptions): Promise<T> {
+        return this.request<T>('POST', path, body, opts);
+    }
+
+    async put<T>(path: string, body?: unknown, opts?: RequestOptions): Promise<T> {
+        return this.request<T>('PUT', path, body, opts);
+    }
+
+    async delete<T>(path: string, opts?: RequestOptions): Promise<T> {
+        return this.request<T>('DELETE', path, undefined, opts);
+    }
+}

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

@@ -0,0 +1,236 @@
+import type { JobQueue } from '../job-queue/types';
+import { getLogger, type Logger } from '../logger';
+import type {
+    AsyncEnqueuedDetail,
+    BusLifecycleEvents,
+    EmitDoneDetail,
+    EventMap,
+    HandlerErrorDetail,
+    SubscribeOptions,
+} from './types';
+
+let _busLogger: Logger | undefined;
+function busLogger(): Logger {
+    if (!_busLogger) _busLogger = getLogger('event-bus');
+    return _busLogger;
+}
+
+/**
+ * Type-safe event bus supporting both synchronous (in-process) and
+ * asynchronous handlers with optional job-queue enqueue instrumentation.
+ */
+export class EventBus<TEvents extends EventMap> {
+    private readonly syncHandlers = new Map<keyof TEvents, Set<TEvents[keyof TEvents]>>();
+    private readonly asyncHandlers = new Map<keyof TEvents, Set<TEvents[keyof TEvents]>>();
+    private readonly asyncHandlerIds = new WeakMap<TEvents[keyof TEvents], string>();
+    private readonly jobQueue: JobQueue | null;
+    private readonly lifecycleBus: EventBus<BusLifecycleEvents> | null;
+    private nextAsyncHandlerId = 0;
+
+    constructor(opts?: {
+        jobQueue?: JobQueue;
+        lifecycleBus?: EventBus<BusLifecycleEvents>;
+    }) {
+        this.jobQueue = opts?.jobQueue ?? null;
+        this.lifecycleBus = opts?.lifecycleBus ?? null;
+    }
+
+    on<K extends keyof TEvents>(event: K, handler: TEvents[K], opts?: SubscribeOptions): void {
+        if (opts?.async) {
+            this.registerAsync(event, handler);
+        } else {
+            this.registerSync(event, handler);
+        }
+    }
+
+    once<K extends keyof TEvents>(event: K, handler: TEvents[K], opts?: SubscribeOptions): void {
+        const wrapped = ((...args: Parameters<TEvents[K]>) => {
+            this.off(event, wrapped as TEvents[K]);
+            handler(...args);
+        }) as TEvents[K];
+
+        this.on(event, wrapped, opts);
+    }
+
+    off<K extends keyof TEvents>(event: K, handler: TEvents[K]): void {
+        const syncSet = this.syncHandlers.get(event);
+        if (syncSet) {
+            syncSet.delete(handler);
+            if (syncSet.size === 0) {
+                this.syncHandlers.delete(event);
+            }
+        }
+
+        const asyncSet = this.asyncHandlers.get(event);
+        if (asyncSet) {
+            asyncSet.delete(handler);
+            if (asyncSet.size === 0) {
+                this.asyncHandlers.delete(event);
+            }
+        }
+    }
+
+    removeAllListeners<K extends keyof TEvents>(event?: K): void {
+        if (event !== undefined) {
+            this.syncHandlers.delete(event);
+            this.asyncHandlers.delete(event);
+        } else {
+            this.syncHandlers.clear();
+            this.asyncHandlers.clear();
+        }
+    }
+
+    async emit<K extends keyof TEvents>(event: K, ...args: Parameters<TEvents[K]>): Promise<void> {
+        const eventName = String(event);
+        const startMs = performance.now();
+        let syncCount = 0;
+        let asyncCount = 0;
+        let errors = 0;
+
+        const syncSet = this.syncHandlers.get(event);
+        if (syncSet) {
+            syncCount = syncSet.size;
+            for (const handler of syncSet) {
+                try {
+                    handler(...args);
+                } catch (error) {
+                    errors++;
+                    const message = error instanceof Error ? error.message : String(error);
+                    busLogger().error('sync handler threw', { event: eventName, error: message });
+                    this.publishHandlerError(eventName, 'sync', message);
+                }
+            }
+        }
+
+        const asyncSet = this.asyncHandlers.get(event);
+        if (asyncSet && asyncSet.size > 0) {
+            const handlers = [...asyncSet];
+            asyncCount = handlers.length;
+
+            for (const handler of handlers) {
+                if (this.jobQueue) {
+                    try {
+                        const jobId = await this.jobQueue.enqueue(eventName, {
+                            event: eventName,
+                            args,
+                            handlerId: this.getAsyncHandlerId(handler),
+                        });
+                        busLogger().debug('async job enqueued', { event: eventName, jobId, handlerCount: 1 });
+                        this.publishAsyncEnqueued(eventName, jobId, 1);
+                    } catch (error) {
+                        errors++;
+                        const message = error instanceof Error ? error.message : String(error);
+                        busLogger().error('async enqueue failed', { event: eventName, error: message });
+                        this.publishHandlerError(eventName, 'async', message);
+                        continue;
+                    }
+                } else {
+                    busLogger().warn('async handlers registered but no JobQueue injected', {
+                        event: eventName,
+                    });
+                }
+
+                try {
+                    await Promise.resolve().then(() => handler(...args));
+                } catch (error) {
+                    errors++;
+                    const message = error instanceof Error ? error.message : String(error);
+                    busLogger().error('async handler threw', { event: eventName, error: message });
+                    this.publishHandlerError(eventName, 'async', message);
+                }
+            }
+        }
+
+        const durationMs = performance.now() - startMs;
+        const detail = args.length === 1 ? args[0] : args.length > 1 ? args : undefined;
+
+        this.publishEmitDone({ event: eventName, syncCount, asyncCount, emitDurationMs: durationMs, errors, detail });
+
+        if (syncCount === 0 && asyncCount === 0) {
+            busLogger().debug('emit with zero handlers', { event: eventName });
+            this.publishEmitNoop(eventName);
+        }
+    }
+
+    listenerCount<K extends keyof TEvents>(event: K, mode?: 'sync' | 'async'): number {
+        const sync = mode !== 'async' ? (this.syncHandlers.get(event)?.size ?? 0) : 0;
+        const async = mode !== 'sync' ? (this.asyncHandlers.get(event)?.size ?? 0) : 0;
+        return sync + async;
+    }
+
+    eventNames(): string[] {
+        const names = new Set<string>();
+        for (const key of this.syncHandlers.keys()) names.add(String(key));
+        for (const key of this.asyncHandlers.keys()) names.add(String(key));
+        return [...names];
+    }
+
+    private registerSync<K extends keyof TEvents>(event: K, handler: TEvents[K]): void {
+        let set = this.syncHandlers.get(event);
+        if (!set) {
+            set = new Set();
+            this.syncHandlers.set(event, set);
+        }
+        set.add(handler);
+    }
+
+    private registerAsync<K extends keyof TEvents>(event: K, handler: TEvents[K]): void {
+        let set = this.asyncHandlers.get(event);
+        if (!set) {
+            set = new Set();
+            this.asyncHandlers.set(event, set);
+        }
+        set.add(handler);
+    }
+
+    private getAsyncHandlerId(handler: TEvents[keyof TEvents]): string {
+        const existing = this.asyncHandlerIds.get(handler);
+        if (existing) return existing;
+
+        const id = `handler-${++this.nextAsyncHandlerId}`;
+        this.asyncHandlerIds.set(handler, id);
+        return id;
+    }
+
+    private publishEmitDone(detail: EmitDoneDetail): void {
+        if (this.lifecycleBus) {
+            try {
+                void this.lifecycleBus.emit('bus.emit.done', detail);
+            } catch {
+                // Lifecycle bus failures must never affect the primary bus.
+            }
+        }
+    }
+
+    private publishEmitNoop(event: string): void {
+        if (this.lifecycleBus) {
+            try {
+                void this.lifecycleBus.emit('bus.emit.noop', { event });
+            } catch {
+                // Swallow.
+            }
+        }
+    }
+
+    private publishHandlerError(event: string, mode: 'sync' | 'async', error: string): void {
+        if (this.lifecycleBus) {
+            const detail: HandlerErrorDetail = { event, mode, error };
+            try {
+                void this.lifecycleBus.emit('bus.handler.error', detail);
+            } catch {
+                // Swallow.
+            }
+        }
+    }
+
+    private publishAsyncEnqueued(event: string, jobId: string, handlerCount: number): void {
+        if (this.lifecycleBus) {
+            const detail: AsyncEnqueuedDetail = { event, jobId, handlerCount };
+            try {
+                void this.lifecycleBus.emit('bus.handler.async.enqueued', detail);
+            } catch {
+                // Swallow.
+            }
+        }
+    }
+}

package/src/event-bus/index.ts

@@ -0,0 +1,9 @@
+export { EventBus } from './event-bus';
+export type {
+    AsyncEnqueuedDetail,
+    BusLifecycleEvents,
+    EmitDoneDetail,
+    EventMap,
+    HandlerErrorDetail,
+    SubscribeOptions,
+} from './types';

package/src/event-bus/types.ts

@@ -0,0 +1,40 @@
+/**
+ * Event bus types — shared constraints for typed pub-sub.
+ */
+
+export type EventMap = Record<string, (...args: never[]) => void>;
+
+export interface SubscribeOptions {
+    /** When true, the handler is dispatched through the async handler path. */
+    async?: boolean;
+}
+
+// ── Lifecycle events ────────────────────────────────────────────────
+
+export interface EmitDoneDetail {
+    event: string;
+    syncCount: number;
+    asyncCount: number;
+    emitDurationMs: number;
+    errors: number;
+    detail?: unknown;
+}
+
+export interface HandlerErrorDetail {
+    event: string;
+    mode: 'sync' | 'async';
+    error: string;
+}
+
+export interface AsyncEnqueuedDetail {
+    event: string;
+    jobId: string;
+    handlerCount: number;
+}
+
+export type BusLifecycleEvents = {
+    'bus.emit.done': (detail: EmitDoneDetail) => void;
+    'bus.emit.noop': (detail: { event: string }) => void;
+    'bus.handler.error': (detail: HandlerErrorDetail) => void;
+    'bus.handler.async.enqueued': (detail: AsyncEnqueuedDetail) => void;
+};

package/src/events/app-events.ts

@@ -0,0 +1,8 @@
+/**
+ * Application event definitions — generic typed event map pattern.
+ * Apps extend this with their own event types.
+ */
+
+export type AppEvents = Record<string, (...args: never[]) => void>;
+
+export type AppInternalEvents = Record<string, (...args: never[]) => void>;

package/src/events/create-system-bus.ts

@@ -0,0 +1,8 @@
+import { EventBus } from '../event-bus/event-bus';
+
+/**
+ * Factory that creates a configured system event bus.
+ */
+export function createSystemBus(): EventBus<Record<string, (...args: never[]) => void>> {
+    return new EventBus();
+}

package/src/events/index.ts

@@ -0,0 +1,2 @@
+export type { AppEvents, AppInternalEvents } from './app-events';
+export { createSystemBus } from './create-system-bus';

package/src/index.ts

@@ -0,0 +1,74 @@
+// API Client
+export { APIClient, type APIClientConfig, APIError, type RequestOptions } from './api-client';
+
+// Event Bus
+export { EventBus, type EventMap, type SubscribeOptions } from './event-bus/index';
+
+// Events
+export type { AppEvents, AppInternalEvents } from './events/index';
+export { createSystemBus } from './events/index';
+
+// Job Queue
+export type {
+    EnqueueOptions,
+    Job,
+    JobHandler,
+    JobQueue,
+    QueueConsumer,
+    QueueConsumerConfig,
+    QueueStats,
+} from './job-queue/index';
+
+// Logger
+export { getLogger, initializeLogger, type Logger, type LogLevel } from './logger';
+
+// Scheduler
+export {
+    CloudflareSchedulerAdapter,
+    getSchedulerAdapter,
+    initScheduler,
+    NodeSchedulerAdapter,
+    NoopSchedulerAdapter,
+    type ScheduledAction,
+    type SchedulerAdapter,
+    setSchedulerAdapter,
+} from './scheduler/index';
+
+// Telemetry
+export {
+    addSpanAttributes,
+    addSpanEvent,
+    extractSqlOperation,
+    getActiveSpan,
+    getDbOperationDuration,
+    getDbOperationErrors,
+    getDbOperationTotal,
+    getEventbusEmitsTotal,
+    getEventbusErrorsTotal,
+    getHttpClientRequestDuration,
+    getHttpClientRequestErrors,
+    getHttpClientRequestTotal,
+    getHttpServerRequestDuration,
+    getHttpServerRequestErrors,
+    getHttpServerRequestTotal,
+    getQueueJobCompletedTotal,
+    getQueueJobEnqueuedTotal,
+    getQueueJobFailedTotal,
+    getQueueJobProcessingDuration,
+    getSchedulerJobDuration,
+    getSchedulerJobExecutedTotal,
+    getSchedulerJobFailedTotal,
+    getTelemetryConfig,
+    getTracer,
+    initMetrics,
+    initTelemetry,
+    isTelemetryEnabled,
+    sanitizeSql,
+    shutdownMetrics,
+    shutdownTelemetry,
+    type TelemetryConfig,
+    type TelemetryConfigPartial,
+    traceAsync,
+    traceSync,
+    withSpan,
+} from './telemetry/index';

package/src/job-queue/index.ts

@@ -0,0 +1,9 @@
+export type {
+    EnqueueOptions,
+    Job,
+    JobHandler,
+    JobQueue,
+    QueueConsumer,
+    QueueConsumerConfig,
+    QueueStats,
+} from './types';